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

2. 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

3. 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

4. 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

5. 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

6. 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

7. 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

8. 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

9. 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
identifies predefined tags that Javadoc processes
Copyright © 2016 Curt Hill

10. 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

11. 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

12. 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

13. 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

14. Wizard Starts
Copyright © 2016 Curt Hill

15. Select Language
Copyright © 2016 Curt Hill

16. Output Selection
Copyright © 2016 Curt Hill

17. Diagram Options
Copyright © 2016 Curt Hill

18. Ready to Run
Copyright © 2016 Curt Hill

19. Done with Run
Copyright © 2016 Curt Hill

20. Index
Copyright © 2016 Curt Hill

21. Class List
Copyright © 2016 Curt Hill

22. 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