GNOME.org
 

Re: [Evolution-hackers] EDS Documentation Effort

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.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]