[LU-16666] Remove or update Doxygen files Created: 24/Mar/23 Updated: 22/Apr/23 Resolved: 22/Apr/23 |
|
| Status: | Resolved |
| Project: | Lustre |
| Component/s: | None |
| Affects Version/s: | None |
| Fix Version/s: | Lustre 2.16.0 |
| Type: | Improvement | Priority: | Minor |
| Reporter: | Tim Day | Assignee: | Tim Day |
| Resolution: | Fixed | Votes: | 0 |
| Labels: | None | ||
| Rank (Obsolete): | 9223372036854775807 |
| Description |
|
The Doxygen files in the build directory are very out of date. I was going to move some http -> https to silence a code scanner warning (and remove some old sun.com links), but it might be better to remove these Doxygen files altogether. Doxygen throws a lot of warnings when you try to use them (since they use obsolete features/flags) and they don't seem to generate useful documentation. They don't seem to have been meaningfully updated in the past 10 years or so.
If people still use these, I can perhaps update them a bit and fix the links. |
| Comments |
| Comment by Gerrit Updater [ 24/Mar/23 ] |
|
"Timothy Day <timday@amazon.com>" uploaded a new patch: https://review.whamcloud.com/c/fs/lustre-release/+/50415 |
| Comment by Patrick Farrell [ 24/Mar/23 ] |
|
Just to put in my vote: I'd definitely like to remove them and any references. We clearly don't use the format. I think there might still be instructions in Gerrit saying to do Doxygen comments on functions? Frankly, I think the rigor enforced by the comment format is somewhat useful and might be good - if we committed to actually enforcing it - but the generated docs have always struck me as kind of a waste of time... They really don't contain much information that can be used outside of the code context. |
| Comment by Tim Day [ 27/Mar/23 ] |
|
The Doxygen comments can be recognized by some IDEs and displayed as info boxes, which is a little helpful. Although they might just display whatever comment is on top of a function. The coding guidelines (https://wiki.lustre.org/Lustre_Coding_Style_Guidelines#Function_comment_blocks) suggest Doxygen. But, some comments don't use any style. Some use something like kernel-doc style, like (https://git.whamcloud.com/?p=fs/lustre-release.git;a=blob;f=lustre/osd-ldiskfs/osd_compat.c;hb=654d5f3fa4df2a0f7275a6da0f050a18881f4f75#l130). A lot of the comments in the code don't seem to be valid Doxygen, since they throw errors when Doxygen tries to parse them. |
| Comment by Gerrit Updater [ 22/Apr/23 ] |
|
"Oleg Drokin <green@whamcloud.com>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/50415/ |
| Comment by Peter Jones [ 22/Apr/23 ] |
|
Landed for 2.16 |