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