https://jira.whamcloud.com This file is an XML representation of an issue en-us 9.4.14 940014 05-12-2023 https://jira.whamcloud.com/browse/LU-16666 Lustre <p>The Doxygen files in the build directory are very out of date. I was going to move some http -&gt; 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.</p> <p> </p> <p>If people still use these, I can perhaps update them a bit and fix the links.</p> LU-16666

Remove or update Doxygen files

Improvement Minor Resolved Fixed Tim Day Tim Day Fri, 24 Mar 2023 17:39:42 +0000 Sat, 22 Apr 2023 18:27:17 +0000 Sat, 22 Apr 2023 18:27:17 +0000 Lustre 2.16.0 0 3 <p>"Timothy Day &lt;timday@amazon.com&gt;" uploaded a new patch: <a href="https://review.whamcloud.com/c/fs/lustre-release/+/50415" class="external-link" target="_blank" rel="nofollow noopener">https://review.whamcloud.com/c/fs/lustre-release/+/50415</a><br/> Subject: <a href="https://jira.whamcloud.com/browse/LU-16666" title="Remove or update Doxygen files" class="issue-link" data-issue-key="LU-16666"><del>LU-16666</del></a> doc: remove unmaintained doxyfiles<br/> Project: fs/lustre-release<br/> Branch: master<br/> Current Patch Set: 1<br/> Commit: b39e9fdc29c08aa0ec9374079ea32c8609f615b2</p> <p>Just to put in my vote:</p> <p>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?</p> <p>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 <b>really</b> don't contain much information that can be used outside of the code context.</p> <p>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.</p> <p>The coding guidelines (<a href="https://wiki.lustre.org/Lustre_Coding_Style_Guidelines#Function_comment_blocks)" class="external-link" target="_blank" rel="nofollow noopener">https://wiki.lustre.org/Lustre_Coding_Style_Guidelines#Function_comment_blocks)</a> suggest Doxygen. But, some comments don't use any style. Some use something like kernel-doc style, like (<a href="https://git.whamcloud.com/?p=fs/lustre-release.git;a=blob;f=lustre/osd-ldiskfs/osd_compat.c;hb=654d5f3fa4df2a0f7275a6da0f050a18881f4f75#l130" class="external-link" target="_blank" rel="nofollow noopener">https://git.whamcloud.com/?p=fs/lustre-release.git;a=blob;f=lustre/osd-ldiskfs/osd_compat.c;hb=654d5f3fa4df2a0f7275a6da0f050a18881f4f75#l130</a>). 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.</p> <p>"Oleg Drokin &lt;green@whamcloud.com&gt;" merged in patch <a href="https://review.whamcloud.com/c/fs/lustre-release/+/50415/" class="external-link" target="_blank" rel="nofollow noopener">https://review.whamcloud.com/c/fs/lustre-release/+/50415/</a><br/> Subject: <a href="https://jira.whamcloud.com/browse/LU-16666" title="Remove or update Doxygen files" class="issue-link" data-issue-key="LU-16666"><del>LU-16666</del></a> doc: remove unmaintained doxyfiles<br/> Project: fs/lustre-release<br/> Branch: master<br/> Current Patch Set: <br/> Commit: c412074ab08535f28576964141c7c0da0a726c3a</p> <p>Landed for 2.16</p> Development Rank 1|i03h73: Rank (Obsolete) 9223372036854775807