API Docs Generation Examples with LDoc & MkDocs

[AntumDeluge]

As per https://github.com/minetest-mods/3d_armor/pull/51#issuecomment-867321886, I created a couple examples for documenting 3d_armor API with LDoc & MkDocs. The documentation is created as an example so is not complete. Keep in mind that I am new to using MkDocs, so it could probably look a lot nicer as is done with Minetest's API.

Examples:

• LDoc:
  • HTML
  • source file
• MkDocs:
  • HTML
  • source file

[BuckarooBanzay]

so, from what i can tell: the mkdocs variant is built from separate markdown files. Isn't it better to keep documentation in-line (and as near as possible) with the code like in the ldoc example? :thinking:

[AntumDeluge]

In the examples I provided, they are actually both built from a separate file (see: source file). However, yes, LDoc can parse Lua docstrings from source code which MkDocs cannot do (as far as I understand). Currently, 3d_armor is not using any Lua docstrings that I am aware of (except in the armor.set_skin_mod method). So if we use LDoc, we can either use an external file (like in my example), or we can just add docstrings to the code.

[AntumDeluge]

I believe that Doxygen has Lua support, or a third party module for Lua support. But LDoc is simpler IMO.

My opinion (with limited knowledge) of the following:

• LDoc: most simple
• MkDocs: best for plain-text readability
• Doxygen: most robust (probably not best for Lua modules)

If you want to do in-line documentation, I would recommend using LDoc or Doxygen (though I am not 100% sure Doxygen has Lua support). If you want to use a separate file for HTML generation and plain-text readabiltity, I would probably suggest MkDocs. MkDocs just uses a markdown formatted file for generating HTML docs. LDoc supports markdown within Lua docstrings.

[SmallJoker]

Oh. I did not see this issue. I only check PRs every now and then. LDoc seems to be more promising, it even has simple markdown support, which would be great to generate a file for easy lookup online.

[AntumDeluge]

@SmallJoker Which would you prefer: Adding Lua docstrings to the code or using a separate file?

[SmallJoker]

No idea.

@BuckarooBanzay Which would you prefer: Adding Lua docstrings to the code or using a separate file?

[BuckarooBanzay]

@BuckarooBanzay Which would you prefer: Adding Lua docstrings to the code or using a separate file?

As mentioned above: my money would be on inline-docs, on the code itself

[AntumDeluge]

I usually prefer inline as well.

[AntumDeluge]

When I get a chance, I will write up some documentation & submit a PR for review.

[AntumDeluge]

Started WIP pull request: #58