Standard for Documenting Mod APIs, Options, Commands, etc.

[AntumDeluge]

I have been using LDoc (a fork of LuaDoc) to create documentation for some of my mods. It might be too much work, but I think it would interesting to have formal guidelines for modders to (optionally) use to document their mods. LDoc is specifically for Lua, for that reason I would recommend it be used in the guidelines. Other than that, Doxygen is the only other source code documentation software that I have used. And I think it can be used with Lua.

An example of HTML documentation generated for a mod using LDoc can be viewed from my listitems mod GitHub page. I am only familiar with the basics of LDoc, & it is probably more capable than what I have used it for so far.

The manual for documenting with LDoc is found here. It is somewhat lacking, unfortunately.

The layout that I use is to create a directory name "docs" for the GitHub pages. Within "docs" I create a configuration file used by the ldoc executable. I also like to create a little helper shell script to speed up the process:

Code: Select all

#!/bin/bash

DOCS="$(dirname $(readlink -f $0))"
ROOT="$(dirname ${DOCS})"
CONFIG="${DOCS}/config.ld"

cd "${ROOT}"

# Clean old files
rm -rf "${DOCS}/api.html" "${DOCS}/scripts" "${DOCS}/modules"
# Create new files
ldoc -c "${CONFIG}" -d "${DOCS}" -o "api" "${ROOT}"

I have LDoc create a file named "api.html", "manual.html", or something similar so that the URL to access the document will be something like "https://antummt.github.io/mod-listitems/api.html".

It would probably be a good idea to create a configuration template that would have any custom functions & tags already defined (example config.ld).

I may myself be interested in writing up a document laying out some guidelines for documenting mods. But that will depend on when I can find some time to do so.

Anyway, just an idea that came to mind from trying to document my own mods. Feedback is appreciated.

[Linuxdirk]

I use a mix of LDoc and PHPDoc to document my code (at least most of the code). Not for parsing it to HTML or so but for documenting the code. To me documentation is as important as the code itself.