Documentation Generators What they are with some examples Copyright © 2016 Curt Hill

Introduction A program that examines source code files and automatically generates documentation from the files They typically look for and format class names and functions They must be language sensitive In addition there is usually a facility that allows the programmer to enter special comments that are used in the result Copyright © 2016 Curt Hill

History The oldest one I could find was mkd from 1986 Still in use on LINUX systems The most famous is probably Javadoc Introduced with the Java language or very shortly thereafter We will likely use Doxygen Copyright © 2016 Curt Hill

Why? Documenting programs has always been a burden for developers It was perceived to be less important that getting things to run Technical writers tend to have a different perspective, attitude and skill set than developers It is very easy to let the documentation lag the code in updates Making it easy greatly helps Copyright © 2016 Curt Hill

Languages A document generator must process the source code of a system of programs It must be designed for a particular language Inside every one of these is a partial parser Does not have to know all the language details but must successfully recognize certain critical portions Copyright © 2016 Curt Hill

Several Languages Haskell - Haddock JavaScript – JSDoc Pascal – fpdoc Perl – POD PhP – phpDocumentor Python - Epydoc Ruby – RDoc SQL – HyperSQL Many languages Several documenters may take multiple languages Copyright © 2016 Curt Hill

Input/Output Generally these programs take the source code as input This is a simple text file Some may also take a binary file The most common output is HTML Some can produce RTF, PDF, PostScript, LaTex, CHM, UNIX man page Copyright © 2016 Curt Hill

Javadoc Originally designed to produce documentation for Java APIs It scans Java files and recognizes classes, methods and properties Produces HTML It has a special comment that allows additional information This comment is the Java multiline command with an additional * Copyright © 2016 Curt Hill

Special Comment Starts with /** Precedes the class or method header and gives additional information Any information is copied into the output file May use HTML formatting tags as well The @ identifies predefined tags that Javadoc processes Copyright © 2016 Curt Hill

Predefined Tags For a class: For a method: @author @version @since For a method: @param @return @throws You may also put in HTML links to other pages Copyright © 2016 Curt Hill

DOxygen Similar to Javadoc: Different as well Scans a directory or directory tree Uses the /** comment Looks for classes, properties, methods and functions Different as well May handle several different languages Uses a control file to set the many options May produce things other than HTML Copyright © 2016 Curt Hill

Control File Looks like a UNIX initialization file The # is the comment Options look like assignments: option = value The default file is larger than 2000 lines Many more comments than directives Copyright © 2016 Curt Hill

Flavors The program itself is a console program There is a GUI program(doxywizard) as well that: Finds the directory or directory tree Sets the options Executes the console program It may also start a browser on the result We will next look at some screen shots that describe usage Copyright © 2016 Curt Hill

Wizard Starts Copyright © 2016 Curt Hill

Select Language Copyright © 2016 Curt Hill

Output Selection Copyright © 2016 Curt Hill

Diagram Options Copyright © 2016 Curt Hill

Ready to Run Copyright © 2016 Curt Hill

Done with Run Copyright © 2016 Curt Hill

Index Copyright © 2016 Curt Hill

Class List Copyright © 2016 Curt Hill

Conclusion This was a program with no preparation for DOxygen Lets do the demo Augment with special comments Regenerate the documentation Copyright © 2016 Curt Hill