Welcome, Guest. Please login or register. Did you miss your activation email?

Author Topic: Nitpicking the Documentation  (Read 5346 times)

0 Members and 1 Guest are viewing this topic.

OniLinkPlus

  • Hero Member
  • *****
  • Posts: 500
    • View Profile
Nitpicking the Documentation
« 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.
I use the latest build of SFML2

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32498
    • View Profile
    • SFML's website
    • Email
Nitpicking the Documentation
« Reply #1 on: May 23, 2011, 07:39:05 am »
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.
Laurent Gomila - SFML developer

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6287
  • Thor Developer
    • View Profile
    • Bromeon
Nitpicking the Documentation
« Reply #2 on: May 23, 2011, 08:29:23 am »
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.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32498
    • View Profile
    • SFML's website
    • Email
Nitpicking the Documentation
« Reply #3 on: May 23, 2011, 08:38:11 am »
Quote
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.

Quote
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 ;)
Laurent Gomila - SFML developer

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6287
  • Thor Developer
    • View Profile
    • Bromeon
Nitpicking the Documentation
« Reply #4 on: May 23, 2011, 10:59:48 am »
Quote from: "Laurent"
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 has two private types (visible in the .hpp code), but they don't appear in the documentation.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32498
    • View Profile
    • SFML's website
    • Email
Nitpicking the Documentation
« Reply #5 on: May 23, 2011, 12:33:24 pm »
Quote
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.
Laurent Gomila - SFML developer

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6287
  • Thor Developer
    • View Profile
    • Bromeon
Nitpicking the Documentation
« Reply #6 on: May 23, 2011, 02:29:59 pm »
Quote from: "Laurent"
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.

Quote from: "Laurent"
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.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32498
    • View Profile
    • SFML's website
    • Email
Nitpicking the Documentation
« Reply #7 on: May 23, 2011, 02:36:14 pm »
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.
Laurent Gomila - SFML developer