On Mon, 2013-11-04 at 15:18 +0900, Tristan Van Berkom wrote: > The goal is to transform the gtk-doc generated html > pages into something that actually looks like a > reference manual. > > Before starting on this long and tedious task of going > through the symbols one by one and checking them off a huge > list, I'd like to share my plans with the list. Hopefully > with some of your feedback I can maximize the value of > this work.
Excellent! I'm happy to help out with this. In the past year or two I've tried to discipline myself to document every new symbol I add, and I've noticed Milan has started doing that now too. So the newer APIs should be in pretty good shape already. A lot of the older APIs are either undocumented or the documentation has... word-rotted... and is no longer accurate. It's a mind-numbing task to fix that stuff up and I've only managed to do it in fits and starts. A concerted effort I think is exactly what we need. > o It probably makes sense here to evaluate also if and > where there are multiple methods of achieving the > same effect in the EDS user facing APIs (some of > the e-data-server-utils.c parts might suffer this). > > In the case there are multiple code paths to the > same result, we should take care to deprecate one > of them. Agreed. In particular, I suggest not wasting much time on the EBook and ECal APIs, as those have been deprecated for a couple years now and are about ready to be dropped. > o One thing I'd like to propose is a unified book for > EDS. > > With a unified documentation package for the whole EDS > API (perhaps excluding camel), a much more useful and > comprehensive table of contents can be built. Also agreed. I don't know why that hadn't occurred to me already. It would make maintenance easier as well. Yes, Camel docs should remain separate. Camel is destined to be split off from the E-D-S git module and should be considered a base dependency of E-D-S, not really part of E-D-S. Another good high-level goal would be to get all the Gtk-Doc warnings fixed for things like improper gtk-doc syntax in comments, mismatched argument names, etc. It would be great we could enable "TESTS = $(GTKDOC_CHECK)" in the Makefile.am and require that to pass as part of the release process. Maybe we should take that one library at a time, though. Anyway, big +1 from me on this whole proposal. Matt _______________________________________________ evolution-hackers mailing list [email protected] To change your list options or unsubscribe, visit ... https://mail.gnome.org/mailman/listinfo/evolution-hackers
