0

It's a simple question. I'm documenting my code following the documentation of the Doxygen, but I have a question: Where I need to document? On the header, on the source or both of them? I know that this is not a rule, but I want to know your opinion about this and what you do on your code and why you do that. For example: I'm documenting the header, and it's nice, the appearance of the code increased, but when I look the source (.cpp) file, I got scared, because there's no documentation and the code is not beautiful, I mean, not the logic, but in beauty (indentation). And everybody knows that even though the code not beautiful (which is difficult in C++) with a documentation it get coolest and easier to read.

Thank you all. (And remember, before you start writing a moral lesson, know that I know that it's not a rule, I'm just wondering what you do)

SH.0x90
  • 532
  • 2
  • 7
  • 19
  • possible duplicate of [Where to put the doxygen comment blocks for an internal library - in H or in CPP files?](http://stackoverflow.com/questions/355619/where-to-put-the-doxygen-comment-blocks-for-an-internal-library-in-h-or-in-cpp) – Stefano Sanfilippo Feb 24 '14 at 17:21
  • Stack Overflow really isn't the place to solicit subjective opinions. – mah Feb 24 '14 at 17:22
  • 1
    In a perfect world, people are not supposed to read the source code. So, put doxygen comments wherever it is easier to change them when you change associated code. – Stefano Sanfilippo Feb 24 '14 at 17:23
  • 2
    Personally I do it in headers, which you're most likely to read when querying the interface for some class. OK fine that might trigger a rebuild, but if you're modifying the documenting comment then odds are, the preconditions for your function have changed, in which case a rebuild is probably not a bad thing. – Lightness Races in Orbit Feb 24 '14 at 17:27

1 Answers1

3

Personally I prefer documenting the h file with that sort of thing. People who need to use your APIs might need your header, but not your cpp. People will never need your cpp without the header. Keep the documentation in one place where everyone who needs it gets it.

m24p
  • 664
  • 4
  • 12
  • 2
    Although after reading http://stackoverflow.com/questions/355619/where-to-put-the-doxygen-comment-blocks-for-an-internal-library-in-h-or-in-cpp I'm not so sure. – m24p Feb 24 '14 at 17:24