Opened 14 years ago

Closed 10 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 14 years ago by Nigel

Owner: changed from Isaac Richards to Nigel
Status: newassigned

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.

comment:2 Changed 13 years ago by Nigel

(In [13898]) Doxygen fixes. Wrong method signature. See #2511

comment:3 Changed 13 years ago by Nigel

(In [13902]) Doxygen fixes. Wrong method signature. See #2511

comment:4 Changed 13 years ago by Nigel

(In [13903]) Doxygen fixes. Correct parameters, remove bad methid sigs. See #2511

comment:5 Changed 13 years ago by Nigel

(In [13905]) Doxygen fixes. Correct parameters, remove bad method sigs. See #2511

comment:6 Changed 11 years ago by Nigel

(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 11 years ago by Nigel

(In [19746]) Doxygen comment fixes. See #2511. (plus unsigned char -> uint8_t to match header)

comment:8 Changed 11 years ago by Nigel

(In [19747]) More Doxygen fixes. See #2511

comment:9 Changed 11 years ago by Nigel

(In [19751]) Doxygen comment fixes. See #2511.

comment:10 Changed 11 years ago by Nigel

(In [20013]) Doxygen fixes (missing const). See #2511.

comment:11 Changed 11 years ago by Nigel

(In [21759]) Doxygen comment fixes. Refs #2511

comment:12 Changed 11 years ago by Nigel

(In [21761]) A few mis-matched method param types picked up as warnings by Doxygen plus Doxygen comment fixes. Refs #2511

comment:13 Changed 11 years ago by Nigel

(In [21765]) Doxygen comment fixes. Refs #2511

comment:14 Changed 11 years ago by Nigel

(In [21766]) Doxygen comment fixes. Refs #2511

comment:15 Changed 11 years ago by stuartm

Component: mythtvDocumentation

comment:16 Changed 10 years ago by robertm

Status: acceptedinfoneeded

Hi Nigel,

Any chance you consider this "done for now?"

comment:17 Changed 10 years ago by Nigel

(In [24650]) Doxygen fixes - a few more mismatched method sigs. Refs #2511

comment:18 Changed 10 years ago by Nigel

Resolution: fixed
Status: infoneededclosed

(In [24651]) Doxygen fix - lets say I'm "dome for now!". Closes #2511

Note: See TracTickets for help on using tickets.