GNOME Bugzilla – Bug 579885
Add code examples to documentation
Last modified: 2010-12-30 14:12:04 UTC
SSIA
Hi. I'd like to start writing some code examples, but I'm not quite sure what's the appropriate method to include them in the docs. Should an example be comprehensive and go in a class's SECTION: comment? Or would it be better to have per-function examples in the comments for each function? Or should they be separate from the code and oriented by some topic? I get frustrated with some APIs due to their lack of examples and direction (like libgsf :D) and am keen to avoid leaving developers uncertain or clueless :)
What I've just committed is sort of what I was intending, though the comments don't have to be restricted to the file's SECTION comment: particularly tricky or useful functions can have examples added too. The aim is not to cover every corner case — just provide examples which will help people get up and running quickly, and will cover most common non-obvious cases. commit 791711972c658d1aca0cddda8077bf7471adb6cd Author: Philip Withnall <philip@tecnocode.co.uk> Date: Mon Oct 26 21:14:02 2009 +0000 Bug 579885 — Add code examples to documentation Added a code example for GDataYouTubeVideo. Helps: bgo#579885 gdata/services/youtube/gdata-youtube-video.c | 35 +++++++++++++++++++++++++- 1 files changed, 34 insertions(+), 1 deletions(-)
Ah, so I wrote a couple examples that might be too comprehensive, but just in source code already. Like, my service one does * create your service * authenticate it * insert an album * upload an image to the album * query for other albums * query for files in one of those albums * download the image while skipping all the unnecessary properties setting and getting, leaving that for their respective classes.
(In reply to comment #3) > Ah, so I wrote a couple examples that might be too comprehensive, but just in > source code already. > > Like, my service one does > > * create your service > * authenticate it > * insert an album > * upload an image to the album > * query for other albums > * query for files in one of those albums > * download the image > > while skipping all the unnecessary properties setting and getting, leaving that > for their respective classes. If that could be split up into a few chunks (like the ones you just enumerated), and some explanatory prose put inbetween, that would be great. With my example, I was trying to show what the relevant superclass methods did, leaving examples of the YouTubeVideo class' methods out, since they're more self-explanatory.
Created attachment 148633 [details] [review] Example of examples I still need to get a feel for these. Should each of those examples have complete but minimalistic code? Like, should there be a main function, or would you prefer just the relevant snippets. Like, I might still use two separate functions to demonstrate asynchronous authentication, but only a block of code for querying albums. Should all variables used in the example be declared? If so (yay clarity), I usually declare variables separately from when I use them. For conciseness, can I do thing like this instead: GDataFeed *album_feed = gdata_picasaweb_service_query_all_albums (service, query, "username", cancellable, callback, NULL, &error); Should examples strongly related to a given function be inserted in the function's comment? The more formal YouTube is associated with the class instead. I think I should avoid overly simple ones, like how to get a width integer, but do illustrate things that involve things like media or a superclass.
Review of attachment 148633 [details] [review]: (In reply to comment #5) > Should each of those examples have complete but minimalistic code? Like, > should there be a main function, or would you prefer just the relevant > snippets. Like, I might still use two separate functions to demonstrate > asynchronous authentication, but only a block of code for querying albums. A main() function is unnecessary; just use the relevant snippets, unless callbacks are involved. If callbacks are involved, you'll want a "main" function (but not main() — just something like authenticate_my_program() or similar). > Should all variables used in the example be declared? If so (yay clarity), I > usually declare variables separately from when I use them. For conciseness, > can I do thing like this instead: > GDataFeed *album_feed = gdata_picasaweb_service_query_all_albums (service, > query, "username", cancellable, callback, NULL, &error); They should be declared, but don't worry about declaring them all beforehand if it's clearer or more concise to declare them inline. > Should examples strongly related to a given function be inserted in the > function's comment? The more formal YouTube is associated with the class > instead. Yes. > I think I should avoid overly simple ones, like how to get a width integer, but > do illustrate things that involve things like media or a superclass. Yes. ::: gdata/services/picasaweb/gdata-picasaweb-service.c @@ +44,3 @@ + * gdata_service_authenticate (GDATA_SERVICE (service), "myGoogleUsername", "mySekr3tPassword", cancellable, &error); + * + * if (gdata_service_is_authenticated (service)) { You can just use the return value of gdata_service_authenticate() rather than calling another function which will return exactly the same thing. @@ +73,3 @@ + * GDataPicasaWebService *service; + * GCancellable *cancellable = g_cancellable_new (); + * /<!-- -->* RHSTODO: do we need a MainLoop in here? *<!-- -->/ Yes, otherwise the callback function can't be called in the main thread. I don't think there's any need to put the main loop code in the example though; just put a note in a comment that this will only work if run in a main loop. @@ +107,3 @@ + * GDataPicasaWebAlbum album; + * + * query = gdata_query_new (/<!-- -->* RHSTODO what to put in here? *<!-- -->/); /<!-- -->* Check examples for #GDataQuery to read more *<!-- -->/ Just pass in NULL, I suppose. @@ +121,3 @@ + * g_object_unref (query); + * + * g_object_unref (cancellable); /<!-- -->* RHSTODO: make sure we should free it like this *<!-- -->/ Yes. @@ +151,3 @@ + * + * file_feed = gdata_picasaweb_service_query_files (service, album, query, cancellable, + * (GDataQueryProgressCallback)progress_cb, NULL, &error); Spaces between typecasts and variable names please! @@ +156,3 @@ + * file = GDATA_PICASAWEB_FILE (files->data); + * + * /<!-- -->* do interesting #GDataPicasaWebFile stuff *<!-- -->/ Might want to give some brief examples of useful things to do here. @@ +196,3 @@ + * inserted_album = gdata_picasaweb_service_insert_album (service, new_album, cancellable, &error); + * + * if (gdata_entry_is_inserted (GDATA_ENTRY (inserted_album)) == TRUE) { /<!-- -->* RHSTODO: does this work with NULL values? *<!-- -->/ You shouldn't call *_is_inserted(), since it doesn't work for NULL values. Just check if (inserted_album != NULL). Insertion functions should never return a non-NULL value if insertion failed. @@ +215,3 @@ + + + Extraneous whitespace!
Created attachment 159533 [details] [review] Patch adding 4 examples for PicasaWeb for creating new albums, uploading new photos, and accessing existing albums and images. Here's an attempt to make a few, more concise examples than in my previous patch, modelled more closely off the YouTube example.
Review of attachment 159533 [details] [review]: Overall, this looks very good. Thanks a lot! Apart from the specific comments below, my only general comment is about indentation. Would it be possible to use tab indentation, as in the rest of libgdata, in the examples? ::: gdata/services/picasaweb/gdata-picasaweb-album.c @@ +41,3 @@ + * GTimeVal timeval; + * GList *thumbnails; + * GDataMediaThumbnail *thumbnail; Put some of these declarations inside the for-loop. @@ +54,3 @@ + * title = gdata_entry_get_title (GDATA_ENTRY (album)); + * summary = gdata_entry_get_summary (GDATA_ENTRY (album)); + * gdata_picasaweb_album_get_timestamp (album, &timeval); What timestamp is this? I wouldn't know whether it's the time when the latest photo was updated, the time the album was originally created, or just the current time of day! @@ +59,3 @@ + * thumbnail = GDATA_MEDIA_THUMBNAIL (thumbnails->data); + * thumbnail_uri = gdata_media_thumbnail_get_uri (thumbnail); + * /<!-- -->* Do something fun with the thumbnails, like download and display them *<!-- -->/ Might want to mention (or actually use) gdata_media_thumbnail_download() here. @@ +66,3 @@ + * + * g_object_unref (album_feed); + * Blank line? ::: gdata/services/picasaweb/gdata-picasaweb-file.c @@ +41,3 @@ + * const gchar *title, *summary, *content_uri; + * GList *contents; + * GDataMediaContent *content; Again, put declarations inside the closest block to where they're used. @@ +52,3 @@ + * height = gdata_picasaweb_file_get_height (photo); + * width = gdata_picasaweb_file_get_width (photo); + * size = gdata_picasaweb_file_get_size (photo); Might want to change the variable to file_size to make it more obvious what this is. @@ +61,3 @@ + * content = GDATA_MEDIA_CONTENT (contents->data); + * content_uri = gdata_media_content_get_uri (content); + * /<!-- -->* Do something fun with the actual images, like download and display them *<!-- -->/ gdata_media_content_download()? @@ +68,3 @@ + * + * g_object_unref (photo_feed); + * Blank line? ::: gdata/services/picasaweb/gdata-picasaweb-service.c @@ +37,3 @@ + * GDataPicasaWebAlbum *album; + * + * service = gdata_picasaweb_service_new ("arbitrary client id"); Should probably mention that it's recommended to be of the form "companyName-applicationName-versionID" (http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html#Request). I need to update the documentation about authentication. @@ +46,3 @@ + * gdata_picasaweb_album_set_location (album, "The Rhine, Germany"); + * + * gdata_picasaweb_service_insert_album (service, album, NULL, NULL); You need to get the result from this, and unref it at the very least. @@ +67,3 @@ + * gdata_entry_set_summary (GDATA_ENTRY (file_entry), "Photo of the world's most beautiful cat."); + * + * gdata_picasaweb_service_upload_file (service, album, file_entry, file_data, NULL, NULL); Again, you need to unref the result from this at the very least. @@ +69,3 @@ + * gdata_picasaweb_service_upload_file (service, album, file_entry, file_data, NULL, NULL); + * + * g_object_unref (file_entry); You need to unref the file_data too.
Created attachment 159661 [details] [review] Patch adding 4 examples for PicasaWeb for creating new albums, uploading new photos, and accessing existing albums and images. Now with * better memory management, * additional documentation for gdata_picasaweb_album_get_timestamp and gdata_picasaweb_service_new, * declarations mixed near the relevant code, * demonstration of relevant downloading APIs, * standard indentation * and more!
Just as a note for when I review the patch more thoroughly and apply it (no need to update the patch, since this is likely the only issue): > + * guint height, width, file_size; file_size should be gsize.
Committed with some minor formatting and type fixes (as above), thanks. :-) Now I just need to get round to writing this sort of example for every other service… commit 4e45d2f1cf199f9eed524769a6344b4dab25d546 Author: Richard Schwarting <aquarichy@gmail.com> Date: Sun May 2 17:44:20 2010 +0100 Bug 579885 — Add code examples to documentation Add code examples to the documentation for GDataPicasaWebAlbum, GDataPicasaWebFile and GDataPicasaWebService. Helps: bgo#579885 gdata/services/picasaweb/gdata-picasaweb-album.c | 54 +++++++++++++++++++- gdata/services/picasaweb/gdata-picasaweb-file.c | 50 ++++++++++++++++++- gdata/services/picasaweb/gdata-picasaweb-service.c | 51 ++++++++++++++++++ 3 files changed, 152 insertions(+), 3 deletions(-)
commit 425fc2eb51acbc2ca4b98961a8903ef23dac0d8f Author: Philip Withnall <philip@tecnocode.co.uk> Date: Sat Dec 11 23:13:23 2010 +0000 core: Add an example of async authentication to the documentation Helps: bgo#579885 gdata/gdata-service.c | 30 ++++++++++++++++++++++++++++++ 1 files changed, 30 insertions(+), 0 deletions(-)
Having had a bit of a think, here's a list of the examples which I think need adding, organised by service: Calendar: • Modifying the ACL on a calendar • Adding a new event • Querying for events (using a GDataCalendarQuery) • Querying for calendars • Doing multiple things with a batch operation Contacts: • Querying for contacts (using a GDataContactsQuery) • Getting and setting a contact's photo • Updating a contact's details (including adding/removing things like IM addresses on the contact) • Adding a new group and adding a contact to it • Querying for groups and differentiating system groups • Doing multiple things with a batch operation Documents: • Downloading a document to disk • Adding a folder • Uploading a document into a folder from disk • Moving a document from one folder to another • Querying for documents (using a GDataDocumentsQuery) • Downloading a specific sheet of a GDataDocumentsSpreadsheet • Modifying the ACL on a document • Doing multiple things with a batch operation PicasaWeb: All done! YouTube: • Querying for standard videos • Uploading a video from disk • Doing multiple things with a batch operation
Calendar examples done. Contacts, Documents and YouTube to go. commit dbf1bb6f99a68d857a4293f5aa8b39786839746d Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 10:41:20 2010 +0000 calendar: Add a code example for listing calendars Helps: bgo#579885 gdata/services/calendar/gdata-calendar-calendar.c | 40 +++++++++++++++++++++ 1 files changed, 40 insertions(+), 0 deletions(-) commit ef3e5a48ce03167e75b545a9140eb46c270c96c1 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 10:41:04 2010 +0000 calendar: Add a code example for querying for events Helps: bgo#579885 gdata/services/calendar/gdata-calendar-query.c | 45 ++++++++++++++++++++++++ 1 files changed, 45 insertions(+), 0 deletions(-) commit 2acf00eb525171944cb022062ad8b990662dfe23 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 10:22:52 2010 +0000 calendar: Add a code example for inserting events Helps: bgo#579885 gdata/services/calendar/gdata-calendar-event.c | 52 ++++++++++++++++++++++++ 1 files changed, 52 insertions(+), 0 deletions(-) commit 83fe275c077268c4a0838e7f1d56b42aeafca807 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 10:04:51 2010 +0000 calendar: Add a code example for calendar ACLs Helps: bgo#579885 gdata/services/calendar/gdata-calendar-service.c | 97 ++++++++++++++++++++++ 1 files changed, 97 insertions(+), 0 deletions(-) commit 71b3e552459ef20d355c70efa92eb4680a798f95 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 09:58:43 2010 +0000 core: Fix a minor typo in the documentation gdata/gdata-upload-stream.c | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-)
…and the one I forgot: commit a246c29d8e4421663eb2448883f31ae3c61b51cb Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 11:11:13 2010 +0000 calendar: Add a code example for using batch operations Helps: bgo#579885 gdata/services/calendar/gdata-calendar-service.c | 71 ++++++++++++++++++++++ 1 files changed, 71 insertions(+), 0 deletions(-)
YouTube done. I couldn't add an example for batch operations to it, as we don't yet support any type of entries (such as playlists) which can have meaningful batch operations performed on them. Contacts and Documents to go. commit 1e0ff1cdc9e70676ad3d21f2174663680b4ce899 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 11:40:11 2010 +0000 youtube: Add a code example for querying standard video feeds Helps: bgo#579885 gdata/services/youtube/gdata-youtube-service.c | 33 ++++++++++++++++++++++++ 1 files changed, 33 insertions(+), 0 deletions(-) commit e6763ee4f5a7fc76d8011f24e756106fc21906a7 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 11:34:00 2010 +0000 youtube: Add a code example for uploading videos Helps: bgo#579885 gdata/services/youtube/gdata-youtube-service.c | 105 ++++++++++++++++++++++++ 1 files changed, 105 insertions(+), 0 deletions(-)
Documents done. Contacts still to do. commit f73bdf5e7c96252685b95864d20ac24646b57b0b Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 13:00:43 2010 +0000 documents: Add a code example for using batch operations Helps: bgo#579885 gdata/services/documents/gdata-documents-service.c | 71 ++++++++++++++++++++ 1 files changed, 71 insertions(+), 0 deletions(-) commit 07de9637c5ce8356dc314110e61162c2e947ac60 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 12:55:50 2010 +0000 documents: Add a code example for document ACLs Helps: bgo#579885 .../services/documents/gdata-documents-document.c | 98 ++++++++++++++++++++ 1 files changed, 98 insertions(+), 0 deletions(-) commit 6dbc1592506b406d8f47cc400459a5d78ff46dd5 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 12:46:14 2010 +0000 documents: Add a code example for downloading a specific spreadsheet sheet Helps: bgo#579885 .../documents/gdata-documents-spreadsheet.c | 53 ++++++++++++++++++++ 1 files changed, 53 insertions(+), 0 deletions(-) commit 6046970e4c38a87ab83e16e58ea7f0b2a04510bb Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 12:34:32 2010 +0000 documents: Add a code example for querying for documents Helps: bgo#579885 gdata/services/documents/gdata-documents-query.c | 47 ++++++++++++++++++++++ 1 files changed, 47 insertions(+), 0 deletions(-) commit e05dd7d6d8ee71ad6bdaec06cae91c2d4b19e748 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 12:24:47 2010 +0000 documents: Add a code example for moving an entry between folders Helps: bgo#579885 gdata/services/documents/gdata-documents-entry.c | 52 ++++++++++++++++++++++ 1 files changed, 52 insertions(+), 0 deletions(-) commit 3151fefa7d4d3e03afed40fa2a71d48091ba84cc Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 12:14:08 2010 +0000 documents: Add a code example for uploading documents Helps: bgo#579885 gdata/services/documents/gdata-documents-service.c | 101 ++++++++++++++++++++ 1 files changed, 101 insertions(+), 0 deletions(-) commit e081c7144e407bf107c2bebf0bf2ae57313f2ea1 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 12:06:42 2010 +0000 documents: Add a code example for adding a new folder Helps: bgo#579885 gdata/services/documents/gdata-documents-folder.c | 35 +++++++++++++++++++++ 1 files changed, 35 insertions(+), 0 deletions(-) commit 5720765671291315397d4f6c182f300548d4cbac Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 12:01:30 2010 +0000 documents: Add a code example for downloading a document Helps: bgo#579885 .../services/documents/gdata-documents-document.c | 57 ++++++++++++++++++++ 1 files changed, 57 insertions(+), 0 deletions(-)
All done! commit c68d0d81945184ca7896360edf05b0aef2bbe899 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 13:55:31 2010 +0000 contacts: Add a code example for using batch operations Helps: bgo#579885 gdata/services/contacts/gdata-contacts-service.c | 70 ++++++++++++++++++++++ 1 files changed, 70 insertions(+), 0 deletions(-) commit 8d5f8f6fb67d32308327f4baf5e3b13bf15a8b2a Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 13:52:12 2010 +0000 contacts: Add a code example for querying for groups Helps: bgo#579885 gdata/services/contacts/gdata-contacts-service.c | 43 ++++++++++++++++++++++ 1 files changed, 43 insertions(+), 0 deletions(-) commit 6e275bc8e3b2c37976338f3753cbd6b5d7179cbc Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 13:46:01 2010 +0000 contacts: Add a code example for adding a new group Helps: bgo#579885 gdata/services/contacts/gdata-contacts-group.c | 52 ++++++++++++++++++++++++ 1 files changed, 52 insertions(+), 0 deletions(-) commit edccc5d9b54f174fd15c477434423749137a0763 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 13:39:05 2010 +0000 contacts: Add a code example for updating a contact's details Helps: bgo#579885 gdata/services/contacts/gdata-contacts-contact.c | 44 ++++++++++++++++++++++ 1 files changed, 44 insertions(+), 0 deletions(-) commit f15d8b4bf226e11278f6344c1bc55d865973a1c0 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 13:28:31 2010 +0000 contacts: Add a code example for getting/setting a contact's photo Helps: bgo#579885 gdata/services/contacts/gdata-contacts-contact.c | 64 ++++++++++++++++++++++ 1 files changed, 64 insertions(+), 0 deletions(-) commit f412792acb1b2787de7efb85d9fcd5df250e7c86 Author: Philip Withnall <philip@tecnocode.co.uk> Date: Thu Dec 30 13:24:02 2010 +0000 contacts: Add a code example for querying for contacts Helps: bgo#579885 gdata/services/contacts/gdata-contacts-query.c | 45 ++++++++++++++++++++++++ 1 files changed, 45 insertions(+), 0 deletions(-)