Source Code Documentation
It is in our best interests to adopt some conventions for documenting source code. For simplicity, we should just use the same conventions that they have been using in class. Also, if you use these conventions, my awk script to extract specifications in HTML will work correctly on them.
- Documentation for procedures and iterators:
- <![CDATA[foo = proc(...
% requires: ...
% modifies: ...
% effects: ...
[body]
end foo</PLAINTEXT>
<LI>of course, you can omit the requires or modifies clause if there isn't one
</UL>
<LI><B>Documentation for clusters:</B>
<UL>
<LI><PLAINTEXT>bar = cluster is ...
% Overview: ...
% written by username, [username, ...]
rep = ...
[equates]
% Abstraction Function: ...
% Rep. Invariants: ...
[procedures & iterators]
end bar
</PLAINTEXT>
</UL>
</UL>
]]></plaintext></li></ul></li></ul></body>