Add libcontacts.7 and libcontacts.h.0 + minor fixes + reorder stuff in libcontacts.h

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 76 insertions, 76 deletions

diff --git a/libcontacts.h b/libcontacts.h
index 6ce77d2..f0aa70b 100644
--- a/libcontacts.h
+++ b/libcontacts.h
@@ -7,6 +7,16 @@
 
 
 /**
+ * Block type for contact
+ */
+enum libcontacts_block_type {
+	LIBCONTACTS_SILENT,      /* The phone shall not call its owner's attention */
+	LIBCONTACTS_BLOCK_OFF,   /* The phone shall appear as turned off */
+	LIBCONTACTS_BLOCK_BUSY,  /* The phone shall appear as busy */
+	LIBCONTACTS_BLOCK_IGNORE /* The phone shall appear as on but with no one answering */
+};
+
+/**
  * Gender of contact
  */
 enum libcontacts_gender {
@@ -17,13 +27,54 @@ enum libcontacts_gender {
 };
 
 /**
- * Block type for contact
+ * Address for contact
  */
-enum libcontacts_block_type {
-	LIBCONTACTS_SILENT,      /* The contact is blocked blocked, the phone shall not call its owner's attention */
-	LIBCONTACTS_BLOCK_OFF,   /* The contact is blocked, phone shall appear as turned off */
-	LIBCONTACTS_BLOCK_BUSY,  /* The contact is blocked, phone shall appear as turned busy */
-	LIBCONTACTS_BLOCK_IGNORE /* The contact is blocked, phone shall appear as on but with no one answering */
+struct libcontacts_address {
+	char *context;            /* Work address (which job)? Home? Summer cabin? … */
+	char *care_of;            /* Care of address, if any */
+	char *address;            /* Address, all lines in one */
+	char *postcode;           /* Post code */
+	char *city;               /* Which city is the post code tied to? */
+	char *country;            /* Which country? */
+	int have_coordinates;     /* Are `.latitude` and `.longitude` defined? */
+	double latitude;          /* Latitudinal GPS coordinate */
+	double longitude;         /* Longitudinal GPS coordinate */
+	char **unrecognised_data; /* Data not recognised by the library */
+};
+
+/**
+ * Birthday of contact
+ */
+struct libcontacts_birthday {
+	unsigned int year;        /* asis,        0 for unknown */
+	unsigned char month;      /* january = 1, 0 for unknown */
+	unsigned char day;        /* asis,        0 for unknown */
+
+	/**
+	 * This is applicable only if the birthday
+	 * is on a leap day. One non-leap years, a
+	 * birthday that occurs on a leap day is
+	 * observed the day after the leap day had
+	 * it existed; but if this flag is set, the
+	 * person observes his birthday the day
+	 * before instead.
+	 * 
+	 * (Even if it is not true (as it wasn't in
+	 * the past), the leap day is treated as if at
+	 * the end of the month, for example a person
+	 * born 1970-02-27, would celebrate his birthday
+	 * on 1980-02-27, not on 1980-02-28; similarly,
+	 * person born 1980-02-27 would celebrate his
+	 * birthday on 1989-02-27, not on 1989-02-26.)
+	 * 
+	 * For example, if a person is born 2000-02-29,
+	 * his birthday is observed 2011-03-01, but if
+	 * this flag is set, he observes it on 2011-02-28
+	 * instead.
+	 */
+	unsigned char before_on_common;
+
+	char **unrecognised_data; /* Data not recognised by the library */
 };
 
 /**
@@ -47,11 +98,12 @@ struct libcontacts_block {
 };
 
 /**
- * Organisation information for contact
+ * Chat address for contact
  */
-struct libcontacts_organisation {
-	char *organisation;       /* Orginisation the contact belongs to */
-	char *title;              /* The contact's title/role in the orginisation */
+struct libcontacts_chat {
+	char *context;            /* Work account (which job?)? Personal account? … */
+	char *service;            /* What service is the account, must not begin with a dot */
+	char *address;            /* What is the name/address/number of the account */
 	char **unrecognised_data; /* Data not recognised by the library */
 };
 
@@ -65,15 +117,6 @@ struct libcontacts_email {
 };
 
 /**
- * PGP-keys for contact
- */
-struct libcontacts_pgpkey {
-	char *context;            /* Work key (which job?)? Personal key? … */
-	char *id;                 /* The key's fingerprint */
-	char **unrecognised_data; /* Data not recognised by the library */
-};
-
-/**
  * Telephone number for contact
  */
 struct libcontacts_number {
@@ -85,72 +128,29 @@ struct libcontacts_number {
 };
 
 /**
- * Address for contact
- */
-struct libcontacts_address {
-	char *context;            /* Work address (which job)? Home? Summer cabin? … */
-	char *care_of;            /* Care of address, if any */
-	char *address;            /* Address, all lines in one */
-	char *postcode;           /* Post code */
-	char *city;               /* Which city is the post code tied to? */
-	char *country;            /* Which country? */
-	int have_coordinates;     /* Are `.latitude` and `.longitude` defined? */
-	double latitude;          /* Latitudal GPS coordinate */
-	double longitude;         /* Longitudal GPS coordinate */
-	char **unrecognised_data; /* Data not recognised by the library */
-};
-
-/**
- * Site (e.g. web and gopher) for contact
+ * Organisation information for contact
  */
-struct libcontacts_site {
-	char *context;            /* Work site (which job?)? Personal site (what is it used for?)? … */
-	char *address;            /* Address to the site, including protocol */
+struct libcontacts_organisation {
+	char *organisation;       /* Orginisation the contact belongs to */
+	char *title;              /* The contact's title/role in the orginisation */
 	char **unrecognised_data; /* Data not recognised by the library */
 };
 
 /**
- * Chat address for contact
+ * PGP-keys for contact
  */
-struct libcontacts_chat {
-	char *context;            /* Work account (which job?)? Personal account? … */
-	char *service;            /* What service is the account, must not begin with a dot */
-	char *address;            /* What is the name/address/number of the account */
+struct libcontacts_pgpkey {
+	char *context;            /* Work key (which job?)? Personal key? … */
+	char *id;                 /* The key's fingerprint */
 	char **unrecognised_data; /* Data not recognised by the library */
 };
 
 /**
- * Birthday of contact
+ * Site (e.g. web and gopher) for contact
  */
-struct libcontacts_birthday {
-	unsigned int year;        /* asis,        0 for unknown */
-	unsigned char month;      /* january = 1, 0 for unknown */
-	unsigned char day;        /* asis,        0 for unknown */
-
-	/**
-	 * This is applicable only if the birthday
-	 * is on a leap day. One non-leap years, a
-	 * birthday that occurs on a leap day is
-	 * observed the day after the leap day had
-	 * it existed; but if this flag is set, the
-	 * person observes his birthday the day
-	 * before instead.
-	 * 
-	 * (Even if it is not true (as it wasn't in
-	 * the past), the leap day is treated as if at
-	 * the end of the month, for example a person
-	 * born 1970-02-27, would celebrate his birthday
-	 * on 1980-02-27, not on 1980-02-28; similarly,
-	 * person born 1980-02-27 would celebrate his
-	 * birthday on 1989-02-27, not on 1989-02-26.)
-	 * 
-	 * For example, if a person is born 2000-02-29,
-	 * his birthday is observed 2011-03-01, but if
-	 * this flag is set, he observes it on 2011-02-28
-	 * instead.
-	 */
-	unsigned char before_on_common;
-
+struct libcontacts_site {
+	char *context;            /* Work site (which job?)? Personal site (what is it used for?)? … */
+	char *address;            /* Address to the site, including protocol */
 	char **unrecognised_data; /* Data not recognised by the library */
 };
 
@@ -196,11 +196,11 @@ struct libcontacts_contact {
 	char *nickname;
 
 	/**
-	 * Pathname to photoes of the contact, use
+	 * Pathnames to photos of the contact, use
 	 * absolute paths or paths relative to the
 	 * user's home directory
 	 * 
-	 * Applications may desired which photo to
+	 * Applications may decide which photo to
 	 * use based on their size, but put the in
 	 * order of preference
 	 *