DOCUMENTATION.md

UDTopia Documentation Overview

Documentation for UDTopia can be found in:

• The README, a high-level overview of UDTopia, with some simple usage examples.
• The docs, more in-depth explanation of features and how to use them.
• The Javadocs, formal API specifications.
• Policy statements (all-caps .md files in the repo root, like this one) define project policies.

Documentation is hard. If you notice something missing or wrong, please create an issue, and/or submit a PR to fix it!

General Documentation Guidelines

• All documentation and code comments should be written in Plain English. Strive for clarity. Omit needless words. Apart from being easier to read by more people, it also helps machine translation to other languages.

• Use Oxford spelling.

Markdown Guidelines

See the code style guidelines doc for a list of Markdown conventions.

Javadoc Guidelines

• All public and protected members should have Javadoc comments.

• Avoid the @author tag, except if the code author and committer are different people. (Example: code copied from another project.)

• The audience for Javadoc is developers. As such, it should be formal and precise. Be sure to document edge-case behaviour.