Doxygen: 7th subset of marked up files #862
Conversation
There was a problem hiding this comment.
A few first round of comments. Before I go through more, I'm not sure why sometimes lots of text are copied from the "purpose" and other times it's not. I want to understand this before reviewing this PR more. (Apologies, I probably forgot something I should remember).
The bottom line is it comes down to a judgement call while keeping in mind a number of factors and trying to move quickly. One of those factors is definitely consistency, but there is a wide range in the documentation you're given to work with. It would be hard to explain in general what that all entails, I can try to give a flavor though. For the 'brief' I'm always looking for a concise 1 sentence statement. Doxygen formats pages expecting that, so for a long sentence for example, I will sometimes truncate or paraphrase. If I do this, and what I left out seems important enough, I'll reproduce some or all of it in the 'details'. If there is a lot of custom formatting, I'll use a 'verbatim' block. This process though starts to get really time consuming as you start delving into the formatting and digesting the material to paraphrase it, etc. As I've progressed I've had to make the decision to leave some of the 'details' (pun somewhat intended :) for a second pass through. So, I may be including less from Purpose in some cases now then say some earlier batches of files. To get through the total number of files, with the current scheduling for it, I think it's the only way to get the first pass done in the time frame we'd like. Since nothing is being removed, an additional pass through could focus on more of those details. |
|
@MatthewMasarik-NOAA thanks for reminding me of the strategy. This sounds good and we'll just have to make sure if/when a header ever gets removed, no information that's not in doxygen is removed with it. I'll do another pass for typos, etc but this should be good to go as soon as we do a sanity regression test (no expected issues) and the CI is fixed. |
There was a problem hiding this comment.
My results from regtests:
**********************************************************************
********************* non-identical cases ****************************
**********************************************************************
mww3_test_03/./work_PR3_UNO_MPI_e (1 files differ)
mww3_test_03/./work_PR2_UQ_MPI_e (1 files differ)
mww3_test_03/./work_PR2_UNO_MPI_e (1 files differ)
mww3_test_03/./work_PR2_UNO_MPI_d2 (16 files differ)
mww3_test_03/./work_PR1_MPI_d2 (10 files differ)
mww3_test_03/./work_PR3_UNO_MPI_d2_c (17 files differ)
mww3_test_03/./work_PR3_UQ_MPI_d2_c (15 files differ)
mww3_test_03/./work_PR3_UNO_MPI_d2 (12 files differ)
mww3_test_03/./work_PR2_UQ_MPI_d2 (16 files differ)
mww3_test_03/./work_PR3_UQ_MPI_d2 (16 files differ)
ww3_ta1/./work_UPD0F_U (0 files differ)
ww3_tp2.10/./work_MPI_OMPH (7 files differ)
ww3_tp2.16/./work_MPI_OMPH (4 files differ)
ww3_tp2.17/./work_ma (1 files differ)
ww3_tp2.17/./work_a (1 files differ)
ww3_tp2.17/./work_mc1 (1 files differ)
ww3_tp2.17/./work_mb (1 files differ)
ww3_tp2.17/./work_mc (1 files differ)
ww3_tp2.17/./work_ma1 (1 files differ)
ww3_tp2.17/./work_c (1 files differ)
ww3_tp2.17/./work_b (1 files differ)
ww3_tp2.6/./work_ST0 (1 files differ)
ww3_tp2.6/./work_ST4 (1 files differ)
ww3_tp2.6/./work_pdlib (1 files differ)
ww3_ts4/./work_ug_MPI (1 files differ)
ww3_ufs1.3/./work_a (3 files differ)
Pull Request Summary
Doxygen documentation has been added for a subset of source files.
Description
The following 10 files have been marked up with
doxygentags:The following 2 files have also been marked with
doxygentags,though the
htmloutput does not display all the documentedsubroutines. These will be put aside for troubleshooting when time
allows. Similar behavior has been seen before, and I don't
currently know the problem(s). A running list has been started here #861. For these two recent files, many (though not all, see w3sic5md.F90: POLYROOTS), have an underscore character '_' in their name.
Please also include the following information:
Issue(s) addressed
Commit Message
Doxygen documentation added, 7th subset.
Check list
p branch.
thub.com/NOAA-EMC/WW3/wiki/Code-Management#checklist-for-a-developer-submittin
g-to-develop).
umber](https://github.com/NOAA-EMC/WW3/wiki/Code-Management#checklist-for-upda\
ting-version-number) checklist.
re is added.
Testing
to be added?)
ler)?
e [list](https://github.com/NOAA-EMC/WW3/wiki/How-to-use-matrix.comp-to-compar\
e-regtests-with-develop#4-look-at-results) of known non-identical tests.)
CompFull.txt and matrixCompSummary.txt):