Dyalog 2008
ADOC
Kai Jaeger
APL Team Ltd
Types Of Documentation
- The "big picture"
- A reference
The Big Picture
- A document (Word, PDF...)
- A help file
- A presentation
- A video
- ...
Whatever is appropriate
The Reference
A reference can be made by using all sorts of technology:
- A help file
- A presentation
- ...
Problems 1
Distance: The farer away the doc is, the more likely it is not updated in case of enhancement/changes
Debugging: Nobody is going to debug the documentation - nobody!
Problems 2
What is worse? A documentation that is...
- incomplete
- inaccurate
- faulty
- not available at all
.
Principles
- The documentation must be as close to the code as possible
- Generate the documentation automatically
- Make adding information to what can be extracted automatically as easy as possible
.
OO
With OO, many pieces of information can be extracted from the class definition
- List public fields, properties and methods
- Mention properties like shared/instance and readonly
- Tell syntax of constructor, destructors and methods
- Process inheritance
- Deal with :Included code
.
End