Documentation: Doxygen compatibillity #10032
Replies: 4 comments 2 replies
-
I'm not a fan of this. When I need to find how a function works, I can search header files. But that's just my preference. |
Beta Was this translation helpful? Give feedback.
-
I approve of using doxygen for this, and I think it would help lower the bar to code development. For me, I'm not used to working with C++, so I always forget to check the header files, and the comments in the source honestly suck. For generating based on the header files, larger comments seem a bit annoying, since it makes it harder to scroll through the header files. If it were generating solely based on source files, I would be more than happy about it... although I think we'd need to manually go through to make sure that it didn't assign comments to specific functions that were originally meant as labels for whole sections. I'm not sure the Python script approach works well enough for it to be worth it, especially since I don't think your implementation currently has |
Beta Was this translation helpful? Give feedback.
-
All in all, this sounds interesting and potentially very useful. That being said, I rather dislike the idea of having to convert all our single comments into three line comments, especially where the first and last lines are basically waste space. That just sounds like it will make everything, visually speaking, take up so much more space and necessitate vastly more scrolling in order to read and do stuff. I skimmed the documentation and it looked like they might have some single line options /// or //! I think?, and I'd prefer that. |
Beta Was this translation helpful? Give feedback.
-
I've used Doxygen in a lot of projects and having a standard header above all functions, classes and methods makes the code quite quite easy to read. (Since one always knows how to read a header, regardless of the file one is viewing.) The extra lines that the header take are usually well worth the space they take. Adding comments in a structured format also has the additional benefit that developers also briefly spend some time explaining (in simple terms) what their new functions are doing. Just spending this additional bit of time sometimes bring a lot of good, valuable, insights, before reviewers even look at the code and the comments. |
Beta Was this translation helpful? Give feedback.
-
Summary
I have a branch, doxygen, in which I added a doxygen config file to generate documentation from the source code.
If that was enough I would just PR that file but there is a problem about this, doxygen only recognizes comments in a specific format. So the documentation with just that config file would still be cool, but could be better if it recognized some of the comments we already have.
Luckily I was able to convert all comments(that are necessary, meaning those in front of functions and classes) in our code with a simple python script.
Problem:
While the conflicts generated by this will be easily fixable, I expect there will be at least some, e.g. when I update with master when I was 30 commits behind I got about 20 conflicts. This is something I would take as a price but of course there may be other opinions. So I am asking coders and devs alike if this is something you want. I personally find such an autogenerated resource very helpful and it could even be hosted on the ES website "endless-sky.github.io" for ease of access.
The style
This is just about the style of the comments, I chose the one that is proposed first on this page: https://www.doxygen.nl/manual/docblocks.html
Which looks like this:
This is really simple and easy to use, but please if you want to have a look at the other styles on the website too.
If this gets done
If this gets done I propose some rules for new code contributions from that point on, or maybe just one rule:
Every function/class should have a comment in the header file describing what it is doing.
Easy as that, should be doable.
For functions that already exist but have no comment, I am sure with time we can fill out more and more of the holes.
What would it look like?
Like this: https://risingleaf.github.io/esdocs.github.io/generated/html/d7/d10/classAccount.html
Beta Was this translation helpful? Give feedback.
All reactions