List:Internals« Previous MessageNext Message »
From:Davi Arnaut Date:April 11 2010 2:13pm
Subject:Re: doxygen comments in header files
View as plain text  
On 4/11/10 10:33 AM, Davi Arnaut wrote:
>
>> Also, it would be great if someone could summarize what are
>> the suggestions, and what are the pros an cons. (Tor?) Otherwise
>> this discussion can go on forever.
>
> I think there is really just one suggestion. In a nutshell, document
> interface in headers, document implementation in source file.
>

A summary of the pros and cons given in the dicussion:

Pros:

- Installed headers (without source file) will have documentation.
- Separation between interface and implementation documentation. Reduced 
signal-to-noise ratio: it is possible to generate documentation for a 
target audience. That is, interface docs won't be encumbered with 
internal details. Assuming there is usually two audiences (users and 
implementors) and that implementors can be users (think modular design).
- Wisdom of crowds: it's a somewhat standard practice.
   http://tinyurl.com/ydc386c http://tinyurl.com/y8wz2dd
   Provides a somewhat better experience (least surprising). In this 
case, there aren't significant gains by just being different.

Cons:

- See Monty's remarks.
Thread
doxygen comments in header filesGuilhem Bichot31 Mar
  • Re: doxygen comments in header filesTor Didriksen6 Apr
    • Re: doxygen comments in header filesGuilhem Bichot6 Apr
      • Re: doxygen comments in header filesMats Kindahl6 Apr
    • Re: doxygen comments in header filesKristian Nielsen6 Apr
      • Re: doxygen comments in header filesGuilhem Bichot9 Apr
        • Re: doxygen comments in header filesTimour Katchaounov11 Apr
          • Re: doxygen comments in header filesDavi Arnaut11 Apr
            • Re: doxygen comments in header filesDavi Arnaut11 Apr
            • Re: doxygen comments in header filesSergei Golubchik11 Apr
              • Re: doxygen comments in header filesGuilhem Bichot12 Apr
                • Re: doxygen comments in header filesTor Didriksen12 Apr
                  • Re: doxygen comments in header filesGuilhem Bichot12 Apr
                    • Re: doxygen comments in header filesTor Didriksen12 Apr
                  • Re: doxygen comments in header filesSergei Golubchik12 Apr
            • Re: doxygen comments in header filesMichael Widenius13 Apr
              • Re: doxygen comments in header filesDavi Arnaut13 Apr
    • Re: doxygen comments in header filesMichael Widenius6 Apr
      • Re: doxygen comments in header filesMARK CALLAGHAN6 Apr
        • Re: doxygen comments in header filesMichael Widenius13 Apr
  • Re: doxygen comments in header filesDavi Arnaut7 Apr
    • Re: doxygen comments in header filesGuilhem Bichot7 Apr
    • Re: doxygen comments in header filesKonstantin Osipov9 Apr
  • Re: doxygen comments in header filesIngo Strüwing12 Apr
    • Re: doxygen comments in header filesGuilhem Bichot15 Apr
      • Re: doxygen comments in header filesIngo Strüwing15 Apr
        • RE: doxygen comments in header filesVladislav Vaintroub16 Apr