[RFC] citro3d documentation

[oreo639]

This is a work in progress pr to finish the documentation for citro3d.
You can check out the pr's docs here:
https://oreo639.github.io/citro3d/index.html

Warning:
This may contain mistakes or poor wording choices.
Comments are welcome.

Note: The PR should be mostly complete, however the last commit will need to be changed when merged.

[fincs]

1/N review done, definitely will be more

[thejsa]

Proofreading for spelling and grammar; s/ctrulib/libctru; and a handful of suggestions to help things read more naturally.

[oreo639]

Thank you for the review. Sorry about the typos.

Just copying these down so they don't get buried.
What still needs to be looked into:

• [RFC] citro3d documentation #54 (comment)
• [RFC] citro3d documentation #54 (comment)
• [RFC] citro3d documentation #54 (comment)

[ian-h-chamberlain]

This PR looks great! It may have gotten a little stale but would still be valuable to have. Any chance of it being revived and/or accepted + published? I have been using https://oreo639.github.io/citro3d/index.html as my go-to for citro3d docs and would love to see this upstreamed and officially published.

If it would be helpful, I can try to review or help any other way, but I am of the opinion that any amount of docs is better than none! Let me know if there's any way to help see this PR through across the finish line.

[oreo639]

Thanks for the comments.

Here is a brief overview of what needs to be finished:

• shadows and lighting
• proctex
• fog

These are things I would preferably experiment with and write applications using them and I just haven't gotten around to that yet.

Here is a list of other remaining tasks in order from most to least important:

• Proofreading (grammar mistakes are certainly an issue, but I am primarily concerned about misleading/incorrect descriptions and missing notes/pitfalls that may not be obvious to new users of the library, one that I have since been informed of but need to commit is C3D_SetScissor(), as an example, which requires you to take into account the rotation of the screen)
• Better descriptions (There is no point in having doFoo() -> Does foo. type descriptions)
• Grouping everything. (similar to citro2d)
• Possibly provide a basic description on how to use the library (similar to libtheora's documentation)

I'm sorry about the delay, my attention has primarily been focused on other projects, but I'll try to look into this more in two weeks give or take.
Any comments or feedback would be greatly appreciated.

[ian-h-chamberlain]

@oreo639 thanks for updating! I have not been using the library for long so I'm not sure how much review help I could provide, but I left some comments/questions for things I saw in the PR.

Depending how the maintainers feel, I think it could be valuable to merge the PR even as-is and allow for future documentation improvements to come in separately, but maybe they'd rather have everything all at once?

[ian-h-chamberlain]

missing doc for C3D_EarlyDepthTest ?

[ian-h-chamberlain]

couple of other missing docs here as well, it looks like, but these functions also seem to be pretty self-explanatory so it may not be worth adding.

[ian-h-chamberlain]

I'm not really enough of a domain expert to review all the descriptions, but I'd love to see this accepted in some form! Thanks for your efforts @oreo639 — this looks like a huge undertaking and having citro3d documentation like this would be super valuable!

[Golem642]

Does anyone know anything about fog/gas rendering? The wiki's empty of description with just the source code shown

[fincs]

There is already a fog example. As for gas support, the current code in citro3d is unfinished. I intend to revisit this soon.