[Mono-docs-list] Updating Gtk# docs

[Joshua Tauberer]

Mike Kestner wrote:
> 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.

Well, right now it's not installed anywhere at all.  Getting it is 
pretty trivial, though.  svn co ...; make, and that's it.

> I am
> using a hacked version of the monodoc updater that is built in
> gtk-sharp/doc/updater currently.

Right.  I wrote monodocer specifically to be a drop-in replacement for 
the old updater.  I'm not sure what you've changed, but the old one 
suffered from a wide range of problems, including generating bad 
(stringified) signatures, not updating metadata when it changes, not 
doing attributes well, etc. etc.

> This update tool seems like a good candidate to be moved. 

It would be nice to have a place for documentation tools, which would 
make sense in the monodoc area, but I don't have strong feelings about it.

>>It generates a 2 megabyte diff of changes
> 
> The word "ouch" comes to mind.

Yeah, but it's not making up changes for no good reason.  Unless the 
Monodoc XML format changes, the Gtk# docs are in need of much updating.

> So the docs currently list a bunch of inherited interfaces that
> shouldn't be explicitly shown in the docs?

Yes.  Well, it depends on what the meaning of "shouldn't" is.  It's not 
incorrect to list them if the type implements it (via its base type), 
but it's really just redundant clutter.

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

(I mean the <TypeSignature Language="C#"> and <MemberSignature...> nodes.)

This might have been introduced into the main Mono docs by an earlier 
monodocer, so I'm not sure if this applies to Gtk#: structs were listed 
as sealed, interfaces were listed as abstract, there were bad 
abstract+virtual combinations, and more.  (And this all shows up in 
Monodoc.)  In any event, whatever signature strings are being generated 
now, they don't match exactly with what is present in the files.

For the return/value nodes: monodocer simply changes the element's name.

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

Yeah, nothing is destroyed by any of this.  Unless names of members or 
the parameters to methods/indexers have changed, everything is fine.  If 
those things have changed, Monodocer may add new documentation sections 
for what it thinks are new members, but it won't delete anything that 
has user-written documentation (unless the --delete option is given).

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

It's not quite that bad.  :)

If I can adapt Monodocer to make it easier to get the Gtk# docs updated 
faster, I can do that.

-- 
- Joshua Tauberer

http://taubz.for.net

** Nothing Unreal Exists **