diff --git a/lib/principal.c b/lib/principal.c
index d9d8e0c..80e6934 100644
--- a/lib/principal.c
+++ b/lib/principal.c
@@ -97,16 +97,16 @@ shishi_principal_default_set (Shishi * handle, const char *principal)
 /**
  * shishi_parse_name:
  * @handle: Shishi library handle created by shishi_init().
- * @name: input principal name string, e.g. imap/address@hidden
+ * @name: input principal name string, e.g. imap/mail.gnu.org@@GNU.ORG.
  * @principal: newly allocated output string with principal name.
  * @realm: newly allocated output string with realm name.
  *
- * Split principal name (e.g., "address@hidden") into two
- * newly allocated strings, the principal ("simon"), and the realm
- * ("JOSEFSSON.ORG").  If there is no realm part in NAME, REALM is set
+ * Split principal name (e.g., "simon@@JOSEFSSON.ORG") into two
+ * newly allocated strings, the @principal ("simon"), and the @realm
+ * ("JOSEFSSON.ORG").  If there is no realm part in @name, @realm is set
  * to NULL.
  *
- * Return value: Returns SHISHI_INVALID_PRINCIPAL_NAME if NAME is NULL
+ * Return value: Returns SHISHI_INVALID_PRINCIPAL_NAME if @name is NULL
  *   or ends with the escape character "\", and SHISHI_OK if
  *   successful.
  **/