Embedded XML Documentation for Fortran 90 and C/C++ Brett N. DiFrischia RS Information Systems NOAA | GFDL

Documentation Foundation of successful software projects Eases development and implementation An absolute necessity for large applications and libraries Often the least maintained portion of any software development effort

Example

Embedded Documentation Benefits Comments next to definition One file to maintain Drawbacks Not easy to navigate Documentation may not be near source counterpart Documentation may not be there at all

HTML Documentation Benefits More navigation options Easier to read Can be more organized Drawbacks More files to maintain May need to know HTML to do so Difficult to follow a standard interface Change in format requires change in all HTML files

How Can XML Help? Structured data User defined elements Optional validation Many parsers available Standards for transformation –XSLT –XSL:FO

Example

Embedding XML in Source Identify information to be included Must be in comments Easy to extract –Assuming there is a way to separate source from comments Perform minimal automated enhancements –Identify external dependencies

Example

Example (cont.)

Extracting XML Must be able to separate comments Replace <‘s and &’s with < and &, respectively –Regular expressions can handle this Parse XML –Typically requires native library Remove private text

Transform Web pages –Directly translate, via parser –Translate using XSLT Transform to different format (XML, HTML, etc.) Printed page –XSL-FO Transform to printable format (typically PDF) Interactive –E.g.. AxKit

Software Primarily Perl programs –Modules are either included with the package or downloadable from CPAN External C libraries –Expat –LibXML2 (in the near future) Java program –Xalan

Future Versions More flexible handling of DTDs –Determine element lists using DTDs (internal) W3C XML Schema dependencies –Specific type enforcement Optional validation of XML –Simple enforcement of documentation standard

Highlights Single file to maintain Tags are easy to remember Standardizes appearance Eases transition between document formats Supports adherence to documentation standards Simplifies documentation creation

For More Information Web pages – – Books –Inside XML Steven Holzner, New Riders Pub., 2000 –Inside XSLT Steven Holzner, New Riders Pub., 2002 –XML in a Nutshell, 2 nd Edition Elliotte Rusty Harold, W. Scott Means, O’Reilly & Associates, 2002