Re: API documentation requirements for next releases

["Murray Cumming" <murrayc murrayc com>]

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

To start with, we are talking only about public API. Public API does NOT
change, and we'd be fools to tell people how to go about changing it.

More complex change-documentation for non-public API can be dealt with
next, but let's start out with something simple.

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

This would be a change of terminology that would likely lead to confusion.
Again, it's not necessary to make this extra change at this time. Small
steps.

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

Again, this is for later. I don't think it's a good idea to hit people
with a big new process all at once.

I've ignored the rest of this email. It's just too long.

> 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
> _______________________________________________
> gnome-hackers mailing list
> gnome-hackers gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-hackers
>
>


Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com