SFML community forums
General => SFML website => Topic started by: OniLinkPlus on May 23, 2011, 02:13:32 am
-
Was looking through the documentation, found this:
Structure defining a page if glyphs.
Sorry to nitpick, but I'd like it if this were fixed.
-
Don't be sorry, every mistake deserves to be corrected ;)
But the weird thing is that this structure appears in the documentation, although it's private.
-
Have you set Doxygen's "extract private" option to true?
Generally, you can just not document implementation-defined data. "Not document" includes also comments with // instead of ///. That's at least what I am doing.
-
Have you set Doxygen's "extract private" option to true?
No, apparently only private nested types appear in the doc (not members), and I couldn't find a specific option for that.
Generally, you can just not document implementation-defined data. "Not document" includes also comments with // instead of ///. That's at least what I am doing.
They would still appear in the doc ;)
-
They would still appear in the doc ;)
Not if HIDE_UNDOC_MEMBERS and HIDE_UNDOC_CLASSES are enabled, which I would recommend.
For example, my class thor::Animation (http://www.bromeon.ch/thor/v1.1/doc/classthor_1_1_animation.html) has two private types (visible in the .hpp code), but they don't appear in the documentation.
-
Not if HIDE_UNDOC_MEMBERS and HIDE_UNDOC_CLASSES are enabled, which I would recommend.
Do you still have doxygen warnings for undocumented members/classes, if you enable these options?
My point is that these classes are private and should not appear if "extract private" is disabled.
-
Do you still have doxygen warnings for undocumented members/classes, if you enable these options?
No, it's indeed an advantage that they remind you about forgotten documentations. However, I don't document everything (at least not with ///), so these warnings would annoy me most of the time, while I rarely forget to actually document classes.
My point is that these classes are private and should not appear if "extract private" is disabled.
Yes, that behavior is inconsistent. But it is still one of the smallest bugs and inconsistences in Doxygen. Some months ago, I had a look at the Doxygen source code, fixed some things I found important* and submitted the patches to the developer. Believe me, the code is a real mess, we can be glad Doxygen does its work yet relatively well ;)
But you could write a bug report, maybe somebody knows how to hide private types. I think it wouldn't be difficult once the corresponding code is found, but until you find it...
_________________
* I fixed mainly two bugs: Related global functions (@relates command) are listed as member functions in the group overview, e.g. MyClass::Func instead of Func, and they are marked as "inherited" in the detailed description. Since I use a lot of global functions in my library and didn't have the patience to wait for someone else to take care of the bugs, I decided to experiment a little myself... But it took quite a while.
-
Yes, I should definitely submit a bug report. I don't have the time to fix it myself, and it's a very minor issue anyway.
I'm surprised, I thought that doxygen was much more stable, given its age and its popularity.