Opened 17 years ago
Closed 14 years ago
#2511 closed task (fixed)
Doxygen \fn declarations don't match code
Reported by: | Nigel | Owned by: | Nigel |
---|---|---|---|
Priority: | minor | Milestone: | unknown |
Component: | Documentation | Version: | head |
Severity: | medium | Keywords: | |
Cc: | Ticket locked: | no |
Description
Checking through the Doxygen log, some Doxygen comments aren't processed because they don't match the methods or function prototypes in the code. The code has changed over time, but the comments were not updated at the same time. Having three possible locations for this stuff (header, Doxygen comment, and method/function declaration) is high maintenance.
Removing the \fn lines seems to do the right thing for a few different versions of Doxygen, so I will do that for the offending methods.
Change History (18)
comment:1 Changed 17 years ago by
Owner: | changed from Isaac Richards to Nigel |
---|---|
Status: | new → assigned |
comment:4 Changed 17 years ago by
comment:5 Changed 17 years ago by
comment:6 Changed 15 years ago by
(In [19745]) Kill some Doxygen warnings and re-attach our doc to some methods, by eliminating incorrect method signatures. See #2511. Note the NVP::SetWatched?() one - having (bool blah=false) is enough for Doxygen to not match (bool) or (bool blah).
comment:7 Changed 15 years ago by
comment:12 Changed 15 years ago by
comment:15 Changed 14 years ago by
Component: | mythtv → Documentation |
---|
comment:16 Changed 14 years ago by
Status: | accepted → infoneeded |
---|
Hi Nigel,
Any chance you consider this "done for now?"
comment:17 Changed 14 years ago by
comment:18 Changed 14 years ago by
Resolution: | → fixed |
---|---|
Status: | infoneeded → closed |
I have done most of the necessary changes in [11172], [11229], [11237] and [11241].
I am not proposing to remove the \fn comments from every file. While it would be nice to have consistancy, keeping the \fn line seems tidier in multi-line comment blocks (when the params and return values are documented), and there are some examples where the comments are not beside the functions (libmythtv/diseqc.cpp from line 856 onwards).
Plus, generally: if it isn't broken, don't change it.