[Mono-docs-list] State of Mono Documentation

[Jonathan Pryor]

On Thu, 2008-01-10 at 21:12 -0600, Mike Kestner wrote:
> Document updating/stubbing is done via the monodocer tool.  The tool is
> fairly robust, but can be very noisy.  For example, I have frozen at an
> old revision of monodocer in Gtk# because of some changes which
> generated an avalanche of "whitespace" into the Gtk# documents like
> reordering of member nodes.  These types of issues just add churn to the
> change management footprint, and make it hard to distinguish real
> changes from noise in a project the size of Gtk#.

I must apologize for this (being the one to make this change).

I modified monodocer to sort the <Member/> nodes (based on @MemberName,
number of parameters, return type, etc.), as originally monodocer
generated output in System.Reflection order, which is (1) completely
unspecified, and (2) can change on the whim of Reflection/mcs/etc.

I figured that sorting the output would *reduce* the amount of _future_
ordering changes.

It also helps with making it easier to find duplicated members, as
they'll be next to each other.  (I've found numerous instances of "bad"
duplicate member checking in monodocer -- some fixed only 2 weeks ago --
where the same member would be present multiple times within an XML
file.  I found it easier to see these duplicated nodes when they were
sorted next to each other.)

> I want to focus instead on the offline side to put better tools in the
> hands of library authors and project teams.  My ultimate goal would be
> to integrate monodocer, validater, and assembler into a WYSIWYG editor
> and documentation administration tool.  That rather large goal can be
> segmented into several intermediate milestones.

I like, depending on how far you go. :-)

My own personal plan at the moment is to write an umbrella command-line
program 'mdoc' to better associate the current programs.

For example:
  Old:                  New:
  ---                   ---
  mdassembler           mdoc assemble
  monodocs2html	        mdoc export-html
  monodocs2slashdoc     mdoc export-slashdoc
  mdnormalizer          mdoc normalize
  monodocer             mdoc update
  mdvalidater           mdoc validate
  mod                   mdoc view

I wouldn't remove the old programs, but the idea is that this would
allow a "naming" framework for new programs that wouldn't continually
"pollute" $PATH.  It would also bring some mental consistency; the name
"monodocer" doesn't really make it easily associated with any of the
other apps as seen through e.g. shell tab completion. :-)

I also want to update the command-line arguments of these apps to
increase consistency, e.g. -o vs. -dest or -path, etc.

So my fear is that your integrated WYSIWYG editor would obsolete this
idea.

I like the idea of a WYSIWYG editor, but I don't want to lose the
ability to do separate command-line updates.  I also want to avoid code
duplication.  (For example, `mdoc' will simply execute the existing
$prefix/lib/monodoc/*.exe programs, NOT re-implement them.)

Otherwise, I love the idea. :-)

 - Jon