Writing API reference documentation

The API reference documentation is generated by gtk-doc. It uses comments above the methods to generate this document. The most important onces are located in the interface glue c files.

This is an example

/**
 * tny_account_store_alert:
 * @self: a #TnyAccountTransport object
 * @type: the message type (severity)
 * @prompt: the prompt
 *
 * This jump-to-the-ui method implements showing a message dialog with prompt
 * as prompt. It will return TRUE if the reply was affirmative. Or FALSE if not.
 * 
 * Return value: Whether the user pressed Ok/Yes (TRUE) or Cancel/No (FALSE)
 **/
gboolean 
tny_account_store_alert (TnyAccountStore *self, TnyAlertType type, const gchar *prompt)
{
#ifdef DEBUG
	if (!TNY_ACCOUNT_STORE_GET_CLASS (self)->alert_func)
		g_critical ("You must implement tny_account_store_alert\n");
#endif
	return TNY_ACCOUNT_STORE_GET_CLASS (self)->alert_func (self, type, prompt);
}

Opening these files and improving the documentation there, will change the online and offline version the next time the documentation is generated.

If you added a new type to tinymail, you will need to let gtk-doc know about this

And because gtk-doc sucks in multiple ways, this isn't easy. The most easy way is to simply remove docs/devel/reference and "svn up" to get a new fully cleared copy. The rerun the ./autogen.sh script with both --enable-gtk-doc, --with-html-component=mozembed and --enable-tests. After the make command you will find a new .sgml file in docs/devel/reference/tmpl. Start finetuning that file and don't care about the new file in docs/devel/reference/xml (it will be ignored by the Subversion repository too). Once done add the .sgml file to the repository (send it to somebody with commit access on the repository or however to achieve putting things in the repository).

Most important is, however, to document the new-API methods. Those are typically going to be documented in interface types. Most API in tinymail is indeed exposed via interface types.