[ ESL - Guidelines ]

Euphoria Standard Library (ESL) - Documentation Guidelines

Specific guidelines for documentation

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