Update docs/Documenting.md

[Dragorn421]

Let's actually formalize an agreement on how to handle documentation

[Dragorn421]

Also we need to discuss the documentation style on structs because // comments on struct fields are completely ignored by doxygen (it expects ///, //!, /** or /*! https://doxygen.nl/manual/docblocks.html )
And it would be great to be able to expand explanations on more than a single line

[EllipticEllipsis]

(our current style would require //!<: https://doxygen.nl/manual/docblocks.html#memberdoc )

[EllipticEllipsis]

I think it is appropriate to have something stronger than @note for some things where stuff will break badly if instructions are not followed.

[Dragorn421]

Yeah and i think the default should be @remark since @note is not for trivia stuff but it would end up being / already is used this way

The problem would be that graduation is completely arbitrary though, or can we come up with actual clear "rules"?

I made this to showcase @remark, @note, @attention, @warning

/**
 * Spawn an object file of a specified ID that will persist through room changes.
 *
 * This only starts loading the object, the data will not be available immediately when the function returns.
 *
 * Used for gameplay_keep, Link's object, and the subkeep if any.
 *
 * @return The new object slot corresponding to the requested object ID.
 *
 * @remark This function is not meant to be called externally to spawn object files on the fly.
 * @note When an object is spawned with this function, all objects that come before it in the entry list will be treated as
 * @attention persistent, which will likely cause the memory available for object space to run out.
 * @warning This function is only meant to be called internally on scene load, before the object list from any room is processed.
 */

[EllipticEllipsis]

I usually use @remark like I'd use "Remark:" in a paper, as a tangential thing that's not usage(/argument)-specific, like what the original name of the function is if known.

[EllipticEllipsis]

I usually use @remark like I'd use "Remark:" in a paper, as a tangential thing that's not usage-specific, like what the original name of the function is if known.

[EllipticEllipsis]

@warning is tricky because it can be mixed up with compiler warnings, but I don't love @attention.

[EllipticEllipsis]

I do think there are systems where LaTeX is useful enough to make it worth it (the matrix stuff, probably sys_math3d), but I know I'm in the minority.

(I suppose fundamentally my point would be that "there is no way to write this clearly in the code, and the next best thing is for it to be clear in the Doxygen".)

[Dragorn421]

Maybe we can find a compromise where LaTeX is its own part and doesn't add information besides math, and there's a main separate explanation part that is readable as plain text?

Do you have an example in MM maybe, there's not much LaTeX in OoT and idk how to find it

[EllipticEllipsis]

Does Doxygen generate the correct links if function names are not followed by ()?

[fig02]

I read over this document again after not having read it in a long time, and everything in it mostly still applies to how we approach documentation today.

We still dont really have clear preferences on different doxygen tags like "@note". I tend to not use them at all and just the word "note:" or "see:"
We can either take that section out or make it clear that we arent strict about it at the moment.

I think overall its clear that most people prefer reading docs straight in the source code and dont even bother with generating docs with doxygen.

[fig02]

need a space between "with" and "just"