Latest version of this page, available in Luismi Pena's Home page; Author: lu@coderazzi.net

xmlobjectsDocGui

Documenting XmlObjects

Description

XmlObjectsDocGui is a tool that complements xmlobjects, supporting the automatic generation of Html documentation from the information in the Xml schema used in xmlobjects.

It extracts the comments embedded in the C# definition of the Xml schema, and uses the Xml hierarchy definition to generate the final Html pages. Currently, it only supports Gui handling, and the user cannot choose among different schemas. Specially interesting, on a future version, would be the generation of the full documentation in a single document.

The idea behind XmlObjectsDocGui is to use the normal C# documentation accompanying the C# definition of the Xml Schema, to provide comprehensive documentation for that schema. Microsoft has defined the format of those comments, but the only way to extracting them is by using the C# compiler. This tool requires, therefore:

  • The C# compiler, which will be invoked with the /doc argument.
  • The list of C# files defining the Xml schema.
  • Any DLL file referenced by those C# files.

It is needed also the target directory to store the generated documentation; this documentation is, as Xml, hierarchical, and needs the root type. It is possible to define this root type in the main application form, or require the application to show the list of types from where to select that type.

License and download

XmlObjectsDocGui is delivered as it, without any responsabilities on the author. It is open source, it can be used or modified without any limitations.

This application is only available in source format.

Dependency on XmlObjects

XmlObjectsDocGui is designed to be independent of the xmlobjects library. Better explained, it is designed to be independent of the library version.

The motivation is that the generation of the documentation of the schema depends on how xmlobjects interpretates that schema; it is therefore possible that the same C# structures defines different Xml schemas depending on the version of the library that is used. XmlObjectsDocGui allows therefore to provide the exact library associated to an schema. This requirements has complicated the implementation of this application, but is also a good exercise on dynamic load of libraries.

In any case, XmlObjectsDocGui still requires xmlobjects: to facilitate the usage of the application, it stores information on the last run as a configuration file. This is a Xml configuration file, and it is, obviously, loaded and stored using the xmlobjects library.