Documentation drive

[xoft]

We need to improve the documentation on the API in the Wiki. A LOT. There's been much progress in the API and the documentation is really stale. Even the hooks are now incomplete, and they used to be the best of the best.

Therefore, I ask everyone capable to join in the "Documentation drive". Get your API.txt, pick a class and fix its documentation in the wiki completely. To give you an idea of what to write there, consult the documentation for cBlockArea or cFurnaceEntity, those two are the format what we're looking for:
http://www.mc-server.org/wiki/doku.php?i...cblockarea
http://www.mc-server.org/wiki/doku.php?i...naceentity

Even if you're not sure what individual class functions do, just list them in the Functions table, and put a FIXME into the notes, so that someone else may come and edit only that function's description.

The previous has been obsoleted by the APIDump plugin. To contribute to documentation, have a look at that plugin and consider adding documentation there. Read the rest of this topic for details.

Code samples for common usage would be most welcome, too.

It would be a good idea to drop a line into this thread before you go documenting a class, just in case someone else decided on the very same thing at the same time.

A big thank you to everyone doing this, in advance!

[bearbin]

Once I fix the lua message standardisation, this will be a nice project.

[xoft]

This has died out, somehow. We need a bigger incentive?

[bearbin]

I did a bit with the new hook stuff, but yeah

[xoft]

I've started upgrading APIDump to aid us in generating the wiki contents semi-automatically. The first part's there - it outputs the functions and constants in tables ready-to-copy into the wiki. One has to fill in the args, returns and notes, though. I'd prefer the tool do that for us, too - so we'd keep the documentation somewhere in the git source and generate all the wiki pages from it.

---

Hmm, an idea - do we need to make it a wiki? It might be easier (read: more manageable) for the plugin to just output a set of HTML pages, something like what Doxygen does with C++ sources. It'd ask MCServer for the API, we could feed it a file containing the descriptions of all (some of) the API, the tool will output a folder full of HTML files ready to browse or upload to a website. It could also output a file listing all the API that is present but not documented, and the API that is documented but not present. Then we could replace the API part of the wiki with a link to (a nightbuild of) the HTML API docs.

After all, wiki is meant for human editting, we want the API update process to be automated, so a wiki is not really the best platform.

What do people think about this?

[bearbin]

I think HTML is probably better, as long as we can have comments and usage examples with the functions.

[xoft]

Anything that would go into the Desc file, can be output at whatever format we want.

FakeTruth, is it possible to get raw text dump of the wiki? You mentioned it stored its pages as plaintext files, could we get those? It'd be easier to extract the already-documented stuff from those.

---

So far I've come up with this format for documenting stuff. What do you think?
https://github.com/mc-server/MCServer/bl...PIDesc.lua

[FakeTruth]

Here are all wiki pages

[bearbin]

So far I've come up with this format for documenting stuff. What do you think?
https://github.com/mc-server/MCServer/bl...PIDesc.lua

It seems OK, although markdown would be better for the format. Otherwise, it's good.

[xoft]

Feel free to implement any markdown, but getting it done in Lua is pretty tiresome