List:Internals« Previous MessageNext Message »
From:Guilhem Bichot Date:April 15 2010 4:37pm
Subject:Re: doxygen comments in header files
View as plain text  
Hello Ingo,

Ingo Strüwing a écrit, Le 12.04.2010 14:47:
> Hi Guilhem,
> 
> Guilhem Bichot, 31.03.2010 11:53:
> 
> ...
>>     I would like the rule to be changed at least for class
>> methods: I would like their comment to be in front of the declaration
>> (so inside the class declaration). In short and approximatively: in the
>> ".h" file, not in the ".cc" file.
> 
> After all the pros and cons, I wonder, if a compromise could be
> thinkable: Have the interface specification at both places and have a
> tool that verifies the consistency at commit/push and/or build time?

In theory this is very appealing. It makes happy the ones who want to 
see all doc in the .cc (one single place to jump to), and the ones who 
want to see the API in the .h.
In practice, I don't know how feasible it is.
First it needs a robust consistency checking script, invoked at 
commit/push time. I assume it should focus on checking only the 
identical content of @param, @retval, @return tags in both files?
Then when I commit/push, does the script require me to fix also the 
inconsistencies left by others (assuming there are, for example they had 
disabled commit/push triggers in their session)? Or does it focus only 
on comments I changed?
And, if it sees that I added a @param to a function's implementation, 
how does it locate the corresponding function's declaration (in order to 
check that I changed it too), how does it find the corresponding header 
file? Doesn't this need to have at least as much "parsing" intelligence 
as ctags/etags/doxygen?
So, I don't know...
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