GNOME.org
 

Re: API documentation requirements for next releases


Federico:

This looks really good.  My comments below are all NITS, and only
intended to encourage more consistant language and stronger definitions.
I'm not wed to the terms/definitions I suggest.  If there are other
terms/definitions that make better sense, please suggest them.


Some time ago we discussed adding a requirement for new APIs that enter
the core platform [1]:  those modules which add new APIs must provide
documentation for those APIs.  Thanks to Murray for bringing it up, and
for resurrecting the discussion.


It would probably be more clear to say "those modules which change API
must likewise change documentation" since API can be deprecated, not
just added.

I recommend we use the term "stable interface" instead of public
interface (since all interfaces in free software are publically visible).
Note the "Interface Stability Levels" at this URL:

  http://live.gnome.org/InterfaceSpecification

If we don't like using the terms stable/unstable/private/internal then
we should come up with a better taxonomy.  We should just use consistant
terms.


The release team has decided that we'll try this plan for the 2.14
release.  If it works out well, we'll use it for subsequent releases as
well.  You can see the details here:

	http://live.gnome.org/ReleasePlanning/NewApiDocs


The above Wiki has a fairly light definition of what is an interface.  So
things are most clear, we should have a fairly complete definition of what
types of interfaces can be defined as "stable".  The above Interface
Specification uses this definition which I think is a bit more complete
than on the NewApiDocs Wiki.

    * Libraries - APIs (Application Programming Interface) and ABIs (Application Binary Interface).
    * Command Line - used by applications, configuration and administration tools
    * Input/Output file formats (GConf keys for example)
    * Resource, configuration, and log file names and formats and location
    * Protocols or inter-component messages
    * Environment variables that affect program execution
    * URLs (e.g. web interfaces used by weather, stock-ticket, etc. applets or made visibile in
      programs like gnome-about)

We should probably have a single place on the live.gnome.org Wiki where the
formal definitions are spelled out rather than having different definitions in
different places.  Perhaps the "InterfaceSpecification" document can be where such
definitions live or perhaps migrate the definitions to a page just for such
definitions?

Stable interfaces could be documented in gtk-docs, but placing the documentation in
the man page probably makes more sense for some types of interfaces (command line,
environment variables, config file formats are often documented in section 5).
Though note some command line interfaces are found in the gtk-docs (such as
glib-gettextize in the Glib docs).  It's not necessary for each module to
document exactly the same way, as long as the interfaces are documented
somewhere reasonable, in my opinion.


Summary:

For modules in the core platform [2], we'll require that new APIs and
other public interfaces have documentation.  This includes C functions,
configuration files, GConf keys, and anything that is not internal only.


Another way of saying this is "if it is not documented, nobody should
assume it is a stable interface".  It perhaps should be pointed out that
care should be taken to ensure that interfaces that should be considered
private or internal probably shouldn't be found in the docs.

Perhaps we could also suggest that non-platform libraries that wish to
prepare themselves for entering the platform should label their interfaces
using the "stable" or "unstable" tags.  When all the interfaces have been
marked as "stable", then that would be a way to identify when a library
is perhaps ready for the Platform.


     1. Document any new public interfaces since the last stable version
        of the module (e.g. the jump from 2.12.x to 2.14.0). You can do
        this with gtk-doc.
     2. Mark any newly deprecated interfaces as such.
     3. Any new module proposed for the platform must be fully
        documented.


Should be more clear that newly added interfaces require "Since:" tags.


In each release cycle, the deadline for API documentation of new API is
one week after API freeze.  Lack of compliance will be treated the same
as freeze breaks. 
For this release cycle, API freeze is on 2006/Jan/16.  So, the deadline
for API documentation will be on 2006/Jan/23.


Sounds reasonable to me.  There is typically little interface change
from release to release, so this isn't really so much work.  Holes that
exist in the current docs can just be considered bugs that should eventually
get fixed.  We're making progress in this area, by the way.  Refer here,
note quite a few of these bugs are closed:

   http://live.gnome.org/InterfaceSpecification/Issues


While this involves a little more work for maintainers, it will keep us
honest as a platform.  It will also ensure that we gradually move toward
full coverage of our documentation.


A great goal.  It helps foster a desktop environment with clear and more
complete interface documentation.

--

Brian
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]