Lua annotations convention - beyond-all-reason/RecoilEngine GitHub Wiki

Here's an example of using the documentation header to provide for table of contents support:

/***
 *
 * @function VBO:CopyTo
 *
 * Copies the current content of the buffer to another buffer. That another buffer is expected to have sufficient allocation.

This would look on a table of contents (when we implement a proper index/toc), and on the documentation body later, like this:

{toc}
- VBO:CopyTo Copies the current content of the buffer to another buffer. That another buffer is expected to have sufficient allocation.

{below}
### function VBO:CopyTo

Copies the current content of the buffer to another buffer. That another buffer is expected to have sufficient allocation.

Suggestion is something like this:

/*** Copy the contents of the VBO to another VBO.
 *
 * @function VBO:CopyTo
 *
 * Destination VBO is expected to have sufficient allocation size. When that's not the case, <shit> happens.

Would look rendered like this:

{toc}
- VBO:CopyTo Copy the contents of the VBO to another VBO.

{below}
### function VBO:CopyTo

{highlighted brief description}
Copy the contents of the VBO to another VBO.

{further description}
Destination VBO is expected to have sufficient allocation size. When that's not the case, <shit> happens.

(I took some liberty to rewrite a little bit, VBO: already indicates that it operates on self, and we should know VBO is a buffer already. So I simplified it a little bit, feel free to ignore the rewrite and just consider the brief_description|more_description concept I want to illustrate)

I know when coding we don't care too much about these things with the most detail, and that's perfectly fine. Just wanted to provide information, so we can support the format we want and will support in the future.