[Evolution-hackers] EDS Documentation Effort

[Tristan Van Berkom <tristanvb openismus com>]

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.

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.