start on easy documentation

[seiyria]

@oipo, @sadbear-

I'd like your feedback on this style of documentation. I intend for it to replace some wiki pages, namely REST API, Reduction Calls, and Events. Possibly the Error codes, too, per #717, but we'll see on that.

Possibly, I may also make this documentation tool automatically link to the source code file/line where it came from. Would that be valuable at all?

[Oipo]

I would like to see more specific information and intent regarding the REST API doc. Currently, the parameters itself are barely sufficient to figure out the purpose, let alone data type / format and otherwise accepted values. This goes for return types as well.

I propose adding

TAG:APIROUTE_PARAMETER [<accepted (enum) values>] <desc/example>

Example:

TAG:APIROUTE: PUT | /player/auth/register | {identifier, name, password} | {player, token}

TAG:APIROUTE_PARAMETER identifier string ident + # + name

TAG:APIROUTE_PARAMETER name string [2..20] "AnythingWithoutDots"

TAG:APIROUTE_PARAMETER password string [3..] "4n\'thing"

Would generate: PUT | /player/auth/register | {identifier, name, password} | {player, token} identifier string ident + # + name name string [2..20] "AnythingWithoutDots" password string [3..] "4n\'thing"

[seiyria]

Sure, this would be fine, but IFF it actually generates two separate tables. One for the entries (APIROUTE) and one below for the definitions (APIROUTE_PARAMETER), such that the output would look like so:

Verb	Route	Params	Returned
PUT	/player/auth/register	{identiifer, name, password}	{player, token}

Then a second table is generated:

Parameter	Type	Definition	Restrictions
identifier	string	The player identifier, specified per client.	None
name	string	The players name	no dots, 2-20 characters
password	string	The players password	3+ characters

This means that all routes would be defined above, and all parameters / return values would be described below that. This means I can keep the parser not maintaining context, which I would strongly prefer. Otherwise I might as well just use doks and make a markdown plugin.

[sadbear-]

I agree that some sort of description is necessary for the parameters and return values. Linking to the source code or adding a short description of what each function does (or maybe just specific functions) could be helpful, as it isn't always clear from its route alone.

[seiyria]

Agreed, and this will be much better when it comes to documentation on, say, event emission, because I have not updated that doc, but I know I've added quite a few routes. I'll definitely add a link back to the source code, then. I think a description might get too wordy, as I want to keep this in a simple table, but I'm all for renaming some routes if necessary.

[seiyria]

Check out the updated one and let me know what you think. Quite honestly I don't want to go through and document all of the return values and parameters, though, so that might be another issue entirely. Anyway, mostly just doing a format check here.

[Oipo]

Looks good.

[seiyria]

Works for me. I'll create another issue detailing the TODO with this, as I've only documented params / retvals from two files for now, and I'd like to move on to get the other things documented as well.