On Fri, 2013-12-06 at 19:08 +0900, Tristan Van Berkom wrote:
> On Mon, 2013-11-04 at 15:18 +0900, Tristan Van Berkom wrote:
> > Hi all,
> >
> > I'm starting a little documentation effort this month
> > for the user facing apis in evolution data server. The scope
> > of this project will touch on the libedataserver, libebook,
> > libebook-contacts and libecal APIs (afforded the time I
> > might be able to dig a little deeper into the server side
> > libedata-book / libedata-cal APIs but strictly speaking
> > we want to focus on user facing APIs).
> >
> > 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.
>
> Hi all.
>
> Unfortunately I did not have the time I expected to complete this,
> instead I focused on the new SQLite addressbook rewrite (which was
> well worthwhile, but prevented me from focusing on this work).
>
> I was however able to get many things done, and am committing those
> changes to master presently.
>
> I'll list here what I was capable of getting done in the time I did
> focus on this:
>
> o Unified documentation
>
> Now the EDS documentation is built into a single reference
> manual, this includes the documentation for libedataserver,
> libebackend, libebook, libebook-contacts, libedata-book,
> libecal, libedata-cal.
>
> Also I added an eds-cursor-example.sgml which focuses on the
> cursor example (contacts browser example).
>
> IMO this serves as a good template for creating and adding new
> examples, as the source code for the example is included inline
> in the example sgml, but doesnt clutter the reference documentation
> for EBookClientCursor (instead I provided a link from
> EBookClientCursor reference to the example sgml).
>
> o Move the cursor example to a new examples directory
>
> This prepares the tree for more examples, right now
> there is examples/cursor and any other examples should
> be added in the examples directory.
>
> o Fixed hundreds of gtk-doc build warnings, there are many
> warnings left, mostly coming from the calendar, I would
> estimate there is probably only around 30% of the previous warnings
>
Eeek, Evolution sent my email before I was finished, this occurred
either because of some hot key, or "Send" somehow obtained keyboard
focus... anyway let's continue with this...
To continue with the report above:
o Many many source files received a documentation header
(i.e. the bit with SECTION:e-foo-bar at the top of the source file).
The majority of sources I think are now covered in this respect
at least. The addressbook having received a higher priority from me
as I was more familiar and able to document it.
o Also, I've deprecated all of the alternative classes
to the new EBookSqlite (of which there were *cough* quite
a few).
o In some of the loooong deprecated enumerations from EBook
and ECal, I've added a simple documentation stub and
just marked the enumeration members /*< private >*/.
This allowed me to silence gtk-doc warnings for old
and deprecated stuff which is just not worth documenting
at this point.
One recommendation I have and would like to highlight, is regarding
the way EDS generates enumeration and flag types in a non-standard way.
EDS has some macro which calls glib-mkenums without adding the regular
rules to Makefile.am in the standard subdirectories, and this results in
extra auxiliary files littered about the tree, example:
e-book-types.h, e-book-contacts-types.h, etc.
This has negative effects on documentation (and on source code
readability). Really the enumerations provided by a given class should
be found in the respective class's header file.
The negative effect this has on documentation is that we get these
docbook pages for e-book-contacts-types, grouping together unrelated
enumerations and flag types into one confusing documentation page.
A hack around this would be to work around it in eds-sections.txt
manually, but that would not solve the disconnection of enumeration
types from their respective sources and headers.
Removing these old macros and using standard enumeration generation
rules in the various library Makefile.ams would go a long way to
improve source code readability (and documentation readability).
Also, if someone feels like picking up the torch for this effort,
I think this is the type of work would be great to be done in
a collaborative fashion.
I would recommend that we create a wiki page with a table of
all symbols in the EDS documentation, for each symbol (row) one
could have a column to 'check off issues' for each type of issue:
o Does the symbol respect common language and jargon used
throughout EDS ?
o Does the symbol actually perform as documented ?
o Resolution for the above, i.e. "Yes it did perform to spec"
or "We changed the documentation to match the spec" or
"We changed the implementation to respect the spec, and
added an appropriate test case".
o Does this symbol advertise preconditions ?
o Does this symbol advertise it's side effects ?
o Does this symbol advertise it's guarantees of how it
can be used (or not) in a threaded context ?
(i.e. must it be called in the thread from which it
was created, will signals be emitted in the thread from
which the object was created ?)
Over the course of time while we slowly fill in the table and
check symbols off the list, proper "language" or "jargon" could
be added to a reference table above.
This would be a long and arduous process, but the weight could
be lightened by the aid of new comers (this would be a great
thing to suggest new contributors to help out with, as it
can help them to get familiar with how EDS works without
requiring too much effort on their part, a great "gnome goal"
type of thing I would think).
FWIW, here is a link to how the new unified reference manual
currently looks:
https://people.gnome.org/~tvb/eds-unified-documentation/
It's currently installed as 'eds' under $prefix/share/gtk-doc/html/eds
and shows up in DevHelp as "Evolution-Data-Server Reference Manual".
Enjoy,
-Tristan
>
> >
> > Below is a list (in two categories) of the things I had
> > planned so far.
> >
> > Any comments or suggestions on additional considerations
> > which should be taken would be great.
> >
> > Cheers,
> > -Tristan
> >
> >
> > Abstact / Toplevel category
> > ~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > This is basically a list of the highlevel things I would like
> > to get done:
> >
> > o Every source file should receive a short and long description
> > in the source code.
> >
> > This is kind of a no brainer, of course it would be nice
> > to have some description sections in the docs as they
> > are mostly missing now.
> >
> > o I intend to add more code example snippets throughout
> > the docs.
> >
> > o I also intend to add more compilable example programs,
> > perhaps not as elaborate as the cursor example, but it
> > would be nice to have some working code which can be
> > inlined into the documentation.
> >
> > Perhaps the cursor-example will move to a subdirectory
> > of a root 'examples' directory or such.
> >
> > 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.
> >
> > 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, EDS documentation can be browsed on a web page
> > easily and all the links in the documentation will actually
> > work (currently they only work in DevHelp, or on
> > developer.gnome.org where some custom task runs to fix
> > the links in published docs).
> >
> > There could very well be a technical detail as to
> > why we don't / can't do this already (however my
> > assumption is that it's done this way just because
> > 'everyone does it this way' so far).
> >
> > Doing this would of course require that downstream
> > packagers be notified of the change, in my experience
> > that isn't too difficult.
> >
> > FWIW, I normally build documentation for multiple
> > shared libraries from the same package into a single
> > book for any project I start (I don't have any example
> > that I can rightfully share though, unfortunately).
> >
> > Low level / Per symbol category
> > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > This is a list of things I intend to consider and resolve
> > before checking a symbol off my list of symbols to document.
> >
> > The task can be considered complete once I have checked
> > all symbols in the scope of this effort.
> >
> > o Consistent language
> >
> > Since we're going over the whole API, it's worth trying
> > to make the documentation consistent in what terms are
> > to be used to describe concepts which repeat themselves
> > throughout the documentation.
> >
> > This will probably not be an exact science, but I can
> > build a text file with a list of terms used as I go
> > along and ensure that the same terms are used throughout
> > the docs.
> >
> > o Documentation / Functionality ambiguities
> >
> > Any symbol for which the implementation is found
> > to not behave as described in the documentation,
> > I will open a bug in bugzilla where we can discuss
> > whether the source code should be updated or whether
> > the docs should be changed.
> >
> > o Documentation should be more explicit about which
> > guarantees are made or not.
> >
> > A specific case where the docs are unclear is regarding
> > threading.
> >
> > Now that EDS uses a lot of threaded functionality from GIO,
> > and now that more and more apps/daemons etc are threaded
> > and using GIO, it's more important to document the specific
> > threading guarantees the EClient based APIs might
> > (or might not) provide.
> >
> > o Preconditions and side effects should be documented.
> >
> > Some functions have preconditions which must be met
> > before calling those functions, otherwise they may
> > return errors or produce undefined behavior.
> >
> > For instance, before using EBookClient APIs, the client
> > must have been successfully opened with e_client_open()
> > (this is no longer the case with e_book_client_connect()
> > just an example).
> >
> > Similarly, functions also have side effects which might
> > not be completely clear, or seemingly orthogonal to the
> > purpose of the function call.
> >
> > One example: Calling e_book_client_view_start()
> > "Tells @view to start processing events"
> >
> > Actually, it also means that notification signals
> > will start to be fired after start() and before stop().
> >
> > More confusing though, is that calling e_book_client_view_start()
> > will cause those notifications to be delivered in the GMainContext
> > which was the thread-default at e_book_client_view_start()
> > time. NOT the GMainContext which was thread default at
> > the time that the EBookClientView was created with
> > e_book_client_get_view() as one would naturally expect
> > (actually whatever one expects, the point is that
> > one cannot be certain as it's undocumented).
> >
> > Wherever preconditions and side effects exist, we should
> > ensure that they are always documented.
> >
> >
>
_______________________________________________
evolution-hackers mailing list
[email protected]
To change your list options or unsubscribe, visit ...
https://mail.gnome.org/mailman/listinfo/evolution-hackers
