Re: [JEDI.NET discuss] Documentation

[Marcel B. <ma...@ze...>]

> [...] Soooo, if any of
> you on this list things he's good enough to add that in: please do. When getting the sources of NDoc, you need to look in the
> ndoc/src/Documenter/NativeHtmlHelp2/xslt for the XSL transformations (BTW, the other Html-based documentation outputs also use
> XSLT files, hint, hint).

    no-one? I'll probably be looking at it again soon.

>     I see two options: write a tool to generate/update the xml templates by reflecting an assembly or write a tool to combine
the
> various XML files, translate them and generate the single new XML file. Or does someone know of such a tool (either one of
them'll
> do).

    OK, I have the core stuff for the documentation generation tool ready. It can:

a) reflect an assembly to retrieve a list of types and members (ignoring all those pesky Delphi generated methods and the Unit
class, the unit class should be empty or at least not contain anything public since we do not allow public routines in a unit).
b) generate an empty skeleton based on a) (items that are not required to be documented are generated as a comment; these are
usually inherited methods/properties).
c) if a pre-existing xml file was found during b), the existing texts are merged into the skeleton file (and neatly reformatted as
well; also checks if the text is well-formed XML).
d) if any documented type or member was no longer available, it is moved to a *.removed file (just in case it was because of a
rename and you want to copy-n-paste the texts into the new type/member). Note it will do so only for items that were actually
documented; undocumented items are simply deleted. The removed items are appended to any existing *.removed file.
e) only update the existing .xml file if anything changed (which can be formatting, but I coded such that it will ignore the
timestamp comment when comparing, so no unneccessary changes will need committing to CVS)

    What it still doesn't do:

a) combine the namespace specific .xml files into a single large assembly specific .xml file (needed to get it working in NDoc)
b) perform a check on what sections of the documentation is missing (undocumented params, return values or types/members).

    I'll be cleaning up the sources of the documentation generation core and it's "test" tool cleaned up and committed later. Next
on the list is combining the xml files per assembly.

--
Marcel Bestebroer (Team JEDI) http://delphi-jedi.org
Project JEDI Help coordinator
JEDI.NET team coordinator