On Mon, 2013-11-04 at 12:00 +0000, evolution-hackers-requ...@gnome.org wrote: > Send evolution-hackers mailing list submissions to > evolution-hackers@gnome.org > > To subscribe or unsubscribe via the World Wide Web, visit > https://mail.gnome.org/mailman/listinfo/evolution-hackers > or, via email, send a message with subject or body 'help' to > evolution-hackers-requ...@gnome.org > > You can reach the person managing the list at > evolution-hackers-ow...@gnome.org > > When replying, please edit your Subject line so it is more specific > than "Re: Contents of evolution-hackers digest..." > > > Today's Topics: > > 1. EDS Documentation Effort (Tristan Van Berkom) > > > ---------------------------------------------------------------------- > > Message: 1 > Date: Mon, 04 Nov 2013 15:18:44 +0900 > From: Tristan Van Berkom <trista...@openismus.com> > To: evolution-hackers <evolution-hackers@gnome.org> > Subject: [Evolution-hackers] EDS Documentation Effort > Message-ID: <1383545924.2016.16.camel@tristan-N53SV> > Content-Type: text/plain; charset="UTF-8" > > 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. > > > > > This would be a great help to those that would like to use the code but are trying to work out how to use the various API etc for EDS. An example is worth a thousand words and any prequestises that are needed like when using the call to a Esourceregistry that it must be called in a Glib main loop etc. This info is hard to find especially for those that are beginners.
_______________________________________________ evolution-hackers mailing list evolution-hackers@gnome.org To change your list options or unsubscribe, visit ... https://mail.gnome.org/mailman/listinfo/evolution-hackers
