[Mono-docs-list] Updating Gtk# docs

[Mike Kestner]

On Sun, 2004-12-12 at 12:44 -0500, Joshua Tauberer wrote:
> If any of the Gtk# documenting people want to start using Monodocer to 
> update Gtk# docs, here's the command you'll want to use:

Until monodocer is installed by a package lower on the dependency chain
than Gtk#, I would prefer it not be used to update the Gtk# docs.  I am
using a hacked version of the monodoc updater that is built in
gtk-sharp/doc/updater currently.

Miguel and I have talked about the possibility of moving some of the
non-graphical parts of monodoc into mcs/tools so that Gtk# can use them.
I don't think anything is likely to happen on that before the new year,
however.  This update tool seems like a good candidate to be moved. 

> It generates a 2 megabyte diff of changes (and that's just the Gtk 
> namespace).  You can have it just update type-level metadata by throwing 
> in the --ignoremembers option, which creates only an 800k diff.

The word "ouch" comes to mind.

> The bulk of the changes come down to not including Interface nodes for 
> interfaces that are implied by other interfaces or the base type,

So the docs currently list a bunch of inherited interfaces that
shouldn't be explicitly shown in the docs?  If so, removing these
references seems to be something that shouldn't cause me any pain.
However... 
 
> updating signatures, and changing 'returns' nodes to 'value' nodes for 
> properties.

Updating signatures how? Were the old sigs incorrectly generated by the
old updater?  In what manner?

If these are predictable transformations, can the old docs be moved to
the new signatures?  The 'returns' to 'value' transformation is one that
seems easy enough to preserve existing docs, does the tool do so?

I want to have correct docs in Gtk#, but I would really like to avoid
weeks of effort moving deprecated docs around manually.  

-- 
Mike Kestner <mkestner@novell.com>