[ ESL - Guidelines ]
Euphoria Standard Library (ESL) - Documentation Guidelines
Status of this topic : Agreed upon
- The User Guide should be written from the point of view of the user.
Technical details, that are only meaningful for the developers of the
library, but not for the end-user, should be mentioned as comments
- Something like "... works like function x in language y" as the only
description is not considered a valid documentation, because it should not
be required to know other languages in order to understand
Euphoria related docs. However, they can be used to supplement
the existing documentation to help programmers migrate to Euphoria.
- The documentation of all constants, types and routines is included as
comments in the respective source code file. A special tool
will read this text, and convert it to an HTML documentation,
that looks like the official Euphoria documentation.
- Two additional HTML files will serve as "wrappers" for the
separate documentations of all the modules:
One file contains a table of contents of the whole library, sorted by module.
The other file contains a alphabetical index of all routines, types, and
constants that are supposed to be called by the user.