search

LaG1924 / AltCraft

Minecraft:JE in C++
Apache License 2.0
112 stars 19 forks source link

Documentation #35

Open LaG1924 opened 5 years ago

LaG1924 commented 5 years ago

There is minor problem with documentation for code. It's missing. Doxygen isn't looks good for html-documentation. Alternatives?

MrDullDev commented 3 years ago

I am not sure what do you mean by "doesn't look good"(since doxygen has a lot of downfalls apart from default looks), but assuming you mean esthetics i would recomend sphinx(it was originally python only, but nowadays it supports quite a variety of languages thanks to extensions). Sphinx is quite mature framework(i mean they are even a lot of big projects that use them like llvm and cmake) and it has a lot of themes to choose from on top of that, you can see them here https://www.sphinx-doc.org/en/master/examples.html . Although Sphinx uses Breathe to make use of doxygen generated xml(fun fact doxygen oficial documentation actually mentions it https://www.doxygen.nl/manual/customize.html#xmlgenerator), so it is not exactly standalone solution

Also there is good table of document generators on wiki https://en.wikipedia.org/wiki/Comparison_of_documentation_generators .

There is actually a thing deserving a honorable mention standardese , it is work in progress documentation generator that aims to be next-gen doxygen. As far as i am concerned this page was generated with it https://standardese.github.io/ , but i am not sure since i used it quite a while back and never messed with the visuals(aka i generated only very plane looking html). I mentioned it here since it seems promising

LaG1924 commented 3 years ago

I believe Standardese is a good thing. But this project is still too new, so I would not use it for now (and it lacks some important features that doxygen has). And sphinx looks good too.

But, lately, my attitude towards documentation has changed. In the last project, I wrote only doxygen-style comments for classes, and together with the support from the IDE, this turned out to be enough so that other programmers did not experience difficulties. Separate HTML documentation is required only for libraries or something similar. For End-User projects, only a small guide on how to use it will be enough (in the case of AC, just a list of differences from the original MC should be enough).