Re: [Evolution-hackers] EDS Documentation Effort

[Matthew Barnes <mbarnes redhat com>]

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