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
_______________________________________________
evolution-hackers mailing list
[email protected]
To change your list options or unsubscribe, visit ...
https://mail.gnome.org/mailman/listinfo/evolution-hackers
