GNOME Bugzilla – Bug 413173
Refresh the API documentation
Last modified: 2013-09-14 16:49:30 UTC
It looks like it's been some time since evolution-data-server's API documentation has seen any love. Here's a few things to get the ball rolling. This is all just Gtk-Doc stuff... no changes yet to the documentation itself. - Generate documentation for libedata-cal and libedataserverui. - Add an index to each of the "Table of Contents" pages. - Automatically mark deprecated symbols as such (e.g. EMutex). - Include symbols that have since been added, and remove those that have since been deleted. - Reorder some things to be more intuitive. - Fix some other miscellaneous Gtk-Doc warnings.
Created attachment 83574 [details] [review] Proposed patch Adds the following modules, among other fixes: docs/reference/addressbook/libedata-book docs/reference/libedataserverui Also, comment #0 was supposed to read: - Generate documentation for libedata-book and libedataserverui. ^^^^
Can we add a "Documentation" component for Evolution-Data-Server to Bugzilla?
Matthew, I have approved ross's patch which is a subset of your patch. This seems to have some code refactoring also. It breaks HC freeze atm.
Understood. If you want, we could defer the code refactoring parts until after Evolution 2.10.0 is released. They just fix a couple Gtk-Doc warnings. Or we could just hold off on the whole thing until after the release.
I'd love to see a 2.10 with decent API docs so will happily subset this patch myself if it means it would get into 2.10.
Ross/Matthew, I too would love to see this :-)
Created attachment 84224 [details] [review] gtk-doc only patch This patch is a subset of patch #83574 that only contains the docs/reference changes, and also applies cleanly to current svn. If it gets committed I propose that we pass the rest of the first patch pass the release team, as it is mainly style changes for gtk-doc.
Srini: This is a low-risk change and a good value-add at that. Any reasons we should fancy a freeze-break request for this patch ?
As matthew quoted: "They just fix a couple Gtk-Doc warnings." I really dont want to request a break and push this. The other part of the patch looks fine.
Because I'm impatient and five hours ahead of Matthew I've committed this.
Created attachment 84227 [details] [review] The code patches to make gtk-doc happy This patch is the code-only changes from attachment #83574 [details], which remove some gtk-doc warnings. There is no real change here, it just renames structs.
Created attachment 84234 [details] [review] API docs for libecal This patch adds more API documentation to libecal. Note that the removal of *e_cal_util_resolve_tzid is correct as it isn't implemented anywhere.
Committed the remaining patches to Subversion trunk, revision 7674.