+ * addressbook/backend/ebook/test-client.c (get_cursor_cb): Added

+	some debugging.
+
+	* addressbook/backend/ebook/e-book-listener.c: Added inline
+	documentation for exposed functions.
+	* addressbook/backend/ebook/e-card-cursor.c: same.
+	* addressbook/backend/ebook/e-card.c: same.

svn path=/trunk/; revision=2248

4 files changed, 99 insertions, 15 deletions

diff --git a/addressbook/backend/ebook/e-book-listener.c b/addressbook/backend/ebook/e-book-listener.c
index 826a070148..4f2e278911 100644
--- a/addressbook/backend/ebook/e-book-listener.c
+++ b/addressbook/backend/ebook/e-book-listener.c
@@ -131,13 +131,13 @@ e_book_listener_queue_get_cursor_response (EBookListener        *listener,
 					   Evolution_CardCursor  cursor)
 {
 	EBookListenerResponse *resp;
-
+	
 	resp = g_new0 (EBookListenerResponse, 1);
 
 	resp->op     = GetCursorResponse;
 	resp->status = status;
 	resp->cursor = cursor;
-
+	
 	e_book_listener_queue_response (listener, resp);
 }
 
@@ -215,7 +215,7 @@ impl_BookListener_respond_get_cursor (PortableServer_Servant servant,
 				      const Evolution_CardCursor cursor,
 				      CORBA_Environment *ev)
 {
-	EBookListener *listener = E_BOOK_LISTENER (bonobo_object_from_servant (servant));
+	EBookListener        *listener = E_BOOK_LISTENER (bonobo_object_from_servant (servant));
 	Evolution_CardCursor  cursor_copy;
 
 	cursor_copy = CORBA_Object_duplicate (cursor, ev);
@@ -311,6 +311,9 @@ impl_BookListener_signal_card_changed (PortableServer_Servant servant,
 
 /**
  * e_book_listener_get_book:
+ * @listener: the #EBookListener 
+ *
+ * Returns: the #EBook associated with the @listener.
  */
 EBook *
 e_book_listener_get_book (EBookListener *listener)
@@ -323,6 +326,10 @@ e_book_listener_get_book (EBookListener *listener)
 
 /**
  * e_book_listener_check_pending:
+ * @listener: the #EBookListener 
+ *
+ * Returns: the number of items on the response queue,
+ * or -1 if the @listener is isn't an #EBookListener.
  */
 int
 e_book_listener_check_pending (EBookListener *listener)
@@ -335,6 +342,11 @@ e_book_listener_check_pending (EBookListener *listener)
 
 /**
  * e_book_listener_pop_response:
+ * @listener: the #EBookListener for which a request is to be popped
+ *
+ * Returns: an #EBookListenerResponse if there are responses on the
+ * queue to be returned; %NULL if there aren't, or if the @listener
+ * isn't an EBookListener.
  */
 EBookListenerResponse *
 e_book_listener_pop_response (EBookListener *listener)
@@ -422,6 +434,11 @@ e_book_listener_construct (EBookListener *listener, EBook *book)
 
 /**
  * e_book_listener_new:
+ * @book: the #EBook for which the listener is to be bound
+ *
+ * Creates and returns a new #EBookListener for the book.
+ *
+ * Returns: a new #EBookListener
  */
 EBookListener *
 e_book_listener_new (EBook *book)
diff --git a/addressbook/backend/ebook/e-card-cursor.c b/addressbook/backend/ebook/e-card-cursor.c
index fc9cf051dc..5638041251 100644
--- a/addressbook/backend/ebook/e-card-cursor.c
+++ b/addressbook/backend/ebook/e-card-cursor.c
@@ -46,8 +46,12 @@ e_card_cursor_destroy (GtkObject *object)
 	GTK_OBJECT_CLASS (parent_class)->destroy (object);
 }
 
-/*
- * CORBA Demo::Echo::echo method implementation
+/**
+ * e_card_cursor_get_length:
+ * @cursor: the #ECardCursor whose length is being queried
+ *
+ * Returns: the number of items the cursor references, or -1 there's
+ * an error.
  */
 long
 e_card_cursor_get_length (ECardCursor *cursor)
@@ -63,6 +67,7 @@ e_card_cursor_get_length (ECardCursor *cursor)
 		if (ev._major != CORBA_NO_EXCEPTION) {
 			g_warning("e_card_cursor_get_length: Exception during "
 				  "get_length corba call.\n");
+			ret_val = -1;
 		}
 
 		CORBA_exception_free (&ev);
@@ -70,11 +75,17 @@ e_card_cursor_get_length (ECardCursor *cursor)
 		return ret_val;
 	}
 	else
-		return 0;
+		return -1;
 }
 
-/*
- * CORBA Demo::Echo::echo method implementation
+/**
+ * e_card_cursor_get_nth:
+ * @cursor: an #ECardCursor object
+ * @n: the index of the item requested
+ *
+ * Gets an #ECard based on an index.
+ *
+ * Returns: a new #ECard on success, or %NULL on failure.
  */
 ECard *
 e_card_cursor_get_nth (ECardCursor *cursor,
@@ -96,7 +107,7 @@ e_card_cursor_get_nth (ECardCursor *cursor,
 			CORBA_exception_init (&ev);
 		}
 
-		card = e_card_new(ret_val);
+		card = e_card_new (ret_val);
 #if 0		
 		CORBA_string__free(ret_val, &ev);
 		
@@ -153,6 +164,16 @@ e_card_cursor_get_type (void)
 	return type;
 }
 
+/**
+ * e_card_cursor_construct:
+ * @cursor: an #ECardCursor object
+ * @corba_cursor: an #Evolution_CardCursor
+ *
+ * Wraps an #Evolution_CardCursor object inside the #ECardCursor
+ * @cursor object.
+ *
+ * Returns: a new #ECardCursor on success, or %NULL on failure.
+ */
 ECardCursor *
 e_card_cursor_construct (ECardCursor          *cursor,
 			 Evolution_CardCursor  corba_cursor)
@@ -184,6 +205,15 @@ e_card_cursor_construct (ECardCursor          *cursor,
 	return cursor;
 }
 
+/**
+ * e_card_cursor_new:
+ * @cursor: the #Evolution_CardCursor to be wrapped
+ *
+ * Creates a new #ECardCursor, which wraps an #Evolution_CardCursor
+ * object.
+ *
+ * Returns: a new #ECardCursor on success, or %NULL on failure.
+ */
 ECardCursor *
 e_card_cursor_new (Evolution_CardCursor corba_cursor)
 {
diff --git a/addressbook/backend/ebook/e-card.c b/addressbook/backend/ebook/e-card.c
index 282f1fe215..1cd018f6f7 100644
--- a/addressbook/backend/ebook/e-card.c
+++ b/addressbook/backend/ebook/e-card.c
@@ -109,7 +109,14 @@ e_card_get_type (void)
 	return card_type;
 }
 
-ECard         *e_card_new (char *vcard)
+/**
+ * e_card_new:
+ * @vcard: a string in vCard format
+ *
+ * Returns: a new #ECard that wraps the @vcard.
+ */
+ECard
+*e_card_new (char *vcard)
 {
 	ECard *card = E_CARD(gtk_type_new(e_card_get_type()));
 	VObject *vobj = Parse_MIME(vcard, strlen(vcard));
@@ -123,12 +130,27 @@ ECard         *e_card_new (char *vcard)
 	return card;
 }
 
+/**
+ * e_card_get_id:
+ * @card: an #ECard
+ *
+ * Returns: a string representing the id of the card, which is unique
+ * within its book.
+ */
 char *
 e_card_get_id (ECard *card)
 {
 	return card->id;
 }
 
+/**
+ * e_card_get_id:
+ * @card: an #ECard
+ * @id: a id in string format
+ *
+ * Sets the identifier of a card, which should be unique within its
+ * book.
+ */
 void
 e_card_set_id (ECard *card, const char *id)
 {
@@ -137,7 +159,14 @@ e_card_set_id (ECard *card, const char *id)
 	card->id = g_strdup(id);
 }
 
-char          *e_card_get_vcard (ECard *card)
+/**
+ * e_card_get_vcard:
+ * @card: an #ECard
+ *
+ * Returns: a string in vCard format, which is wrapped by the @card.
+ */
+char
+*e_card_get_vcard (ECard *card)
 {
 	VObject *vobj; /*, *vprop; */
 	char *temp, *ret_val;
diff --git a/addressbook/backend/ebook/test-client.c b/addressbook/backend/ebook/test-client.c
index 3091fede1d..ffe20ee030 100644
--- a/addressbook/backend/ebook/test-client.c
+++ b/addressbook/backend/ebook/test-client.c
@@ -53,11 +53,17 @@ get_cursor_cb (EBook *book, EBookStatus status, ECardCursor *cursor, gpointer cl
 {
 	long length = e_card_cursor_get_length(cursor);
 	long i;
+
+	/* we just added a card, so the length should be >1 */
+	printf ("\n%s: %s(): Number of cards is %ld\n",
+		__FILE__, __FUNCTION__, length);
+	if (length < 1)
+		printf ("*** Why isn't this above zero?? ***\n\n");
 	
 	for ( i = 0; i < length; i++ ) {
 		ECard *card = e_card_cursor_get_nth(cursor, i);
 		char *vcard = e_card_get_vcard(card);
-		printf("[%s]\n", vcard);
+		printf("Get all cards callback: [%s]\n", vcard);
 		g_free(vcard);
 		gtk_object_unref(GTK_OBJECT(card));
 	}
@@ -82,11 +88,13 @@ add_card_cb (EBook *book, EBookStatus status, const gchar *id, gpointer closure)
 
 	vcard = e_card_get_vcard(card);
 	printf ("%g\n", g_timer_elapsed (timer, NULL));
-	printf ("[%s]\n", vcard);
+	printf ("Card added: [%s]\n", vcard);
 	g_free(vcard);
 	gtk_object_unref(GTK_OBJECT(card));
 
+	printf ("Getting cards..\n");
 	e_book_get_all_cards(book, get_cursor_cb, NULL);
+	printf ("Done getting all cards.\n");	
 }
 
 static void
@@ -103,7 +111,7 @@ ebook_create (void)
 	book = e_book_new ();
 
 	if (!book) {
-		printf ("%s: %s: Couldn't create EBook, bailing.\n",
+		printf ("%s: %s(): Couldn't create EBook, bailing.\n",
 			__FILE__,
 			__FUNCTION__);
 		return FALSE;
@@ -126,7 +134,7 @@ main (int argc, char **argv)
 	init_bonobo (argc, argv);
 
 	gtk_idle_add ((GtkFunction) ebook_create, NULL);
-
+	
 	bonobo_main ();
 
 	return 0;