Re: [Evolution-hackers] EDS Documentation Effort

[Tristan Van Berkom <tristanvb openismus com>]

On Mon, 2013-11-04 at 08:01 -0500, Matthew Barnes wrote:
> 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.

Great to hear this is well received ;-)

There will surely be plenty of nit picking of minor details,
so I'll try to batch them together in a way that it's practical
for you to give feedback on.

> 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.

Right, I forgot to mention... deprecated APIs will certainly not be in
the scope of this effort.

> >   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.

Also nice to hear, this will really make a big difference.

I'll also take the opportunity to write up some custom sgml sections
similar to the API docs of GTK+. Specifically I mean one section
dedicated to "Building EDS"... one section dedicated to "Running EDS"
etc.

As far as I can see there is no common place to document any
environment variables which might effect how EDS runs, so it will
be great to have a place for that.

> 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.

Well, being a merged document will mean there will be one directory
'docs/reference/eds' (sitting beside camel) with one eds.types,
eds-sections.txt etc...

But I'm pretty confident I can get it to pass the test, I've been
building the docs a lot and it's clear the majority of warnings
come from the camel directory.

Cheers,
    -Tristan