GNOME.org
 

[evolution-patches] EBook docs patch

Hi,

I've been updating the ebook API docs -- attached is a patch for what I
have so far. Obviously there is more work to do but this is a good
start.

Please CC: me on any replies, I am not on this list.

Ross
-- 
Ross Burton                                 mail: ross burtonini com
                                          jabber: ross burtonini com
                                     www: http://www.burtonini.com./
 PGP Fingerprint: 1A21 F5B0 D8D0 CFE3 81D4 E25A 2D09 E447 D0B4 33DF

? ebook-docs.diff
Index: e-book-listener.h
===================================================================
RCS file: /cvs/gnome/evolution-data-server/addressbook/libebook/e-book-listener.h,v
retrieving revision 1.2
diff -u -r1.2 e-book-listener.h
--- e-book-listener.h	4 Nov 2003 14:30:17 -0000	1.2
+++ e-book-listener.h	2 Dec 2003 10:34:34 -0000
@@ -32,6 +32,7 @@
 
 struct _EBookListener {
 	BonoboObject           parent;
+	/*< private >*/
 	EBookListenerPrivate *priv;
 };
 
Index: e-book-view.h
===================================================================
RCS file: /cvs/gnome/evolution-data-server/addressbook/libebook/e-book-view.h,v
retrieving revision 1.2
diff -u -r1.2 e-book-view.h
--- e-book-view.h	4 Nov 2003 14:30:17 -0000	1.2
+++ e-book-view.h	2 Dec 2003 10:34:34 -0000
@@ -33,6 +33,7 @@
 
 struct _EBookView {
 	GObject     parent;
+	/*< private >*/
 	EBookViewPrivate *priv;
 };
 
Index: e-book.c
===================================================================
RCS file: /cvs/gnome/evolution-data-server/addressbook/libebook/e-book.c,v
retrieving revision 1.8
diff -u -r1.8 e-book.c
--- e-book.c	1 Dec 2003 15:18:31 -0000	1.8
+++ e-book.c	2 Dec 2003 10:34:34 -0000
@@ -182,10 +182,11 @@
  * e_book_add_card:
  * @book: an #EBook
  * @contact: an #EContact
+ * @error: a #GError to set on failure.
  *
  * adds @contact to @book.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise.
  **/
 gboolean
 e_book_add_contact (EBook           *book,
@@ -292,11 +293,12 @@
  * e_book_commit_contact:
  * @book: an #EBook
  * @contact: an #EContact
+ * @error: a #GError to set on failure
  *
  * applies the changes made to @contact to the stored version in
  * @book.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise
  **/
 gboolean
 e_book_commit_contact (EBook           *book,
@@ -375,11 +377,12 @@
  * e_book_get_supported_fields:
  * @book: an #EBook
  * @fields: a #GList
+ * @error: a #GError to set on failure
  *
- * queries @book for the list of fields it supports.  mostly for use
+ * Queries @book for the list of fields it supports. Mostly for use
  * by the contact editor so it knows what fields to sensitize.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise
  **/
 gboolean
 e_book_get_supported_fields  (EBook            *book,
@@ -475,10 +478,11 @@
  * e_book_get_supported_auth_methods:
  * @book: an #EBook
  * @auth_methods: a #GList
+ * @error: a #GError to set on failure
  *
- * queries @book for the list of authentication methods it supports.
+ * Queries @book for the list of authentication methods it supports.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise
  **/
 gboolean
 e_book_get_supported_auth_methods (EBook            *book,
@@ -578,12 +582,13 @@
  * @user: a string
  * @passwd: a string
  * @auth_method: a string
+ * @error: a #GError to set on failure
  *
- * authenticates @user with @passwd, using the auth method
+ * Authenticates @user with @passwd, using the auth method
  * @auth_method.  @auth_method must be one of the authentication
  * methods returned using e_book_get_supported_auth_methods.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise
  **/
 gboolean
 e_book_authenticate_user (EBook         *book,
@@ -662,11 +667,12 @@
  * @book: an #EBook
  * @id: a string
  * @contact: an #EContact
+ * @error: a #GError to set on failure
  *
  * Fills in @contact with the contents of the vcard in @book
  * corresponding to @id.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise
  **/
 gboolean
 e_book_get_contact (EBook       *book,
@@ -766,10 +772,11 @@
  * e_book_remove_contact:
  * @book: an #EBook
  * @id: a string
+ * @error: a #GError to set on failure
  *
  * Removes the contact with id @id from @book.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise
  **/
 gboolean
 e_book_remove_contact (EBook       *book,
@@ -811,13 +818,14 @@
  * e_book_remove_contacts:
  * @book: an #EBook
  * @ids: an #GList of const char *id's
+ * @error: a #GError to set on failure
  *
  * Removes the contacts with ids from the list @ids from @book.  This is
  * always more efficient than calling e_book_remove_contact_by_id if you
  * have more than one id to remove, as some backends can implement it
  * as a batch request.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise
  **/
 gboolean
 e_book_remove_contacts (EBook    *book,
@@ -902,10 +910,14 @@
  * @query: an #EBookQuery
  * @requested_fields a #GList containing the names of fields to return, or NULL for all
  * @max_results the maximum number of contacts to show (or 0 for all)
+ * @book_view: A #EBookView pointer, will be set to the view
+ * @error: a #GError to set on failure
  *
- * need docs here..
+ * Query @book with @query, creating a #EBookView in @book_view with the fields
+ * specified by @requested_fields and limited at @max_results records. On an
+ * error, @error is set and #FALSE returned.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE if successful, #FALSE otherwise
  **/
 gboolean
 e_book_get_book_view (EBook       *book,
@@ -1036,10 +1048,13 @@
  * e_book_get_contacts:
  * @book: an #EBook
  * @query: an #EBookQuery
+ * @contacts: a #GList pointer, will be set to the list of contacts
+ * @error: a #GError to set on failure
  *
- * need docs here..
+ * Query @book with @query, setting @contacts to the list of contacts which
+ * matched. On failed, @error will be set and #FALSE returned.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE on success, #FALSE otherwise
  **/
 gboolean
 e_book_get_contacts (EBook       *book,
@@ -1274,6 +1289,7 @@
 /**
  * e_book_cancel:
  * @book: an #EBook
+ * @error: a #GError to set on failure
  *
  * Used to cancel an already running operation on @book.  This
  * function makes a synchronous CORBA to the backend telling it to
@@ -1285,7 +1301,7 @@
  * blocked e_book function corresponding to current operation will
  * return with a status of E_BOOK_STATUS_CANCELLED.
  *
- * Return value: a #EBookStatus value.
+ * Return value: #TRUE on success, #FALSE otherwise
  **/
 gboolean
 e_book_cancel (EBook   *book,
@@ -1368,6 +1384,16 @@
 
 
 
+/**
+ * e_book_remove:
+ * @book: an #EBook
+ * @error: a #GError to set on failure
+ *
+ * Remove the backing data for this #EBook. For example, with the file backend this
+ * deletes the database file. You cannot get it back!
+ *
+ * Return value: #TRUE on success, #FALSE on failure.
+ */
 gboolean
 e_book_remove (EBook   *book,
 	       GError **error)
@@ -1505,6 +1531,15 @@
 
 
 
+/**
+ * e_book_unload_uri:
+ * @book: an #EBook
+ * @error an #GError to set on failure
+ *
+ * Unload the URI that this book had previously loaded.
+ *
+ * Return value: #TRUE on success, #FALSE otherwise.
+ */
 gboolean
 e_book_unload_uri (EBook   *book,
 		   GError **error)
@@ -1746,6 +1781,18 @@
 	return rv;
 }
 
+/**
+ * e_book_load_source:
+ * @book: an #EBook
+ * @source: the #ESource to load
+ * @only_if_exists: if #TRUE, fail if this source doesn't already exist
+ * otherwise create it first
+ * @error: a #GError to set on failure
+ *
+ * Load the specified source into the book.
+ *
+ * Return value: #TRUE if the source was loaded, #FALSE otherwise.
+ */
 gboolean
 e_book_load_source (EBook *book,
 		    ESource *source,
@@ -1789,6 +1836,12 @@
 	return rv;
 }
 
+/**
+ * e_book_load_local_addressbook:
+ * @book: an #EBook
+ * @error: a #GError
+ *
+ */
 gboolean
 e_book_load_local_addressbook (EBook   *book,
 			       GError **error)
@@ -1811,12 +1864,30 @@
 	return rv;
 }
 
+/**
+ * e_book_get_uri:
+ * @book: an #EBook
+ *
+ * Get the URI that this book has loaded. This string should not be freed.
+ *
+ * Return value: The URI.
+ */
 const char *
 e_book_get_uri (EBook *book)
 {
 	return book->priv->uri;
 }
 
+/**
+ * e_book_get_static_capabilities:
+ * @book: an #EBook
+ * @error: an #GError to set on failure
+ *
+ * Get the list of capabilities which the backend for this address book
+ * supports. This string should not be freed.
+ *
+ * Return value: The capabilities list
+ */
 const char *
 e_book_get_static_capabilities (EBook   *book,
 				GError **error)
@@ -1852,6 +1923,16 @@
 	return book->priv->cap;
 }
 
+/**
+ * e_book_check_static_capability:
+ * @book: an #EBook
+ * @cap: A capability string
+ *
+ * Check to see if the backend for this address book supports the capability
+ * @cap.
+ *
+ * Return value: #TRUE if the backend supports @cap, #FALSE otherwise.
+ */
 gboolean
 e_book_check_static_capability (EBook *book,
 				const char  *cap)
@@ -1865,6 +1946,14 @@
 	return FALSE;
 }
 
+/**
+ * e_book_is_writable:
+ * @book: an #EBook
+ * 
+ * Check if this book is writable.
+ * 
+ * Return value: #TRUE if this book is writable, otherwise #FALSE.
+ */
 gboolean
 e_book_is_writable (EBook *book)
 {
@@ -1942,6 +2031,16 @@
 
 
 
+/**
+ * e_book_get_default_addressbook:
+ * @book: The address of a pointer to an #EBook
+ * @error: A #GError pointer
+ * 
+ * Convience function to open the default address book. Pass it the address of a
+ * #EBook* and if this returns #TRUE, #book is set to an opened #EBook.
+ * 
+ * Return value: #TRUE if the default addressbook was opened, otherwise false.
+ */
 gboolean
 e_book_get_default_addressbook (EBook **book, GError **error)
 {
@@ -1971,6 +2076,14 @@
 	return rv;
 }
 
+/**
+ * e_book_get_addressbooks:
+ * @addressbook_sources: A pointer to a ESourceList* to set
+ * @error: A pointer to a GError* to set on error
+ *
+ * Populate *addressbook_sources with the list of all sources which have been
+ * added to Evolution.
+ */
 gboolean
 e_book_get_addressbooks (ESourceList **addressbook_sources, GError **error)
 {
@@ -2008,6 +2121,15 @@
 
 
 
+/**
+ * e_book_new:
+ *
+ * Creates a new #EBook. Use e_book_load_uri() or
+ * e_book_load_local_addressbook() to access a data store.  Alternatively use
+ * e_book_get_default_addressbook().
+ *
+ * Return value: a new but unopened #EBook.
+ **/
 EBook*
 e_book_new (void)
 {
Index: e-book.h
===================================================================
RCS file: /cvs/gnome/evolution-data-server/addressbook/libebook/e-book.h,v
retrieving revision 1.4
diff -u -r1.4 e-book.h
--- e-book.h	27 Nov 2003 02:29:02 -0000	1.4
+++ e-book.h	2 Dec 2003 10:34:34 -0000
@@ -37,6 +37,7 @@
 
 struct _EBook {
 	GObject       parent;
+	/*< private >*/
 	EBookPrivate *priv;
 };
 
Index: e-contact.h
===================================================================
RCS file: /cvs/gnome/evolution-data-server/addressbook/libebook/e-contact.h,v
retrieving revision 1.3
diff -u -r1.3 e-contact.h
--- e-contact.h	26 Nov 2003 00:35:30 -0000	1.3
+++ e-contact.h	2 Dec 2003 10:34:34 -0000
@@ -180,7 +180,7 @@
 
 struct _EContact {
 	EVCard parent;
-
+	/*< private >*/
 	EContactPrivate *priv;
 };
 
Index: e-vcard.h
===================================================================
RCS file: /cvs/gnome/evolution-data-server/addressbook/libebook/e-vcard.h,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 e-vcard.h
--- e-vcard.h	3 Nov 2003 18:23:57 -0000	1.1.1.1
+++ e-vcard.h	2 Dec 2003 10:34:34 -0000
@@ -92,7 +92,7 @@
 
 struct _EVCard {
 	GObject parent;
-
+	/*< private >*/
 	EVCardPrivate *priv;
 };
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]