Doxygen documentation: Request for development community comments

[MatthewMasarik-NOAA]

Pull Request Summary

Templates for doxygen documentation.

Description

This PR seeks adoption of a set of templates for each Fortran 'code unit' (file, program, subroutine, etc). Each code unit has a section below with the suggested required and optional tags for the template. Links to samples of input and output for the templates are given for each as well. At this time only acceptance of the templates is being considered -- the marked up code and output will follow in a separate PR.

UPDATED: Jan 10th - Addresses comments made by @edwardhartnett

Notes

• The complete doxygen documentation is hosted at: https://matthewmasarik-noaa.github.io/WW3.
• For reference, the complete list of Doxygen Special Commands (Tags) Note: the commands are shown using the \ version, these are equivalent to the @ version.
• Note below: doxygen determines the end of the @brief section by the first period (keep in mind when using '.' in punctuation before the end of the sentence). The blank line following the @brief sentence is not required, but is customary.

Templates

FILE

• Required

!> @file  <file name>
!> @brief  <one sentence description>
!> 
!> @author <author name> @date <dd-Mon-yyyy>

• Optional: @todo, @remark,@remark,@attention,@warning, @copyright.
• Sample
  • Input: w3updtmd.F90,
  • Output: w3updtmd.F90.

MODULE

• Required

!> @brief <one sentence description>    # contents of _1. Purpose_ from original header
!> 
!> @details <extended description>
!>
!> @param <module var 1>
!> ...
!> @param <module var N>
!> @author <author name> @date <dd-Mon-yyyy>

• Note: ALL module variables need documentation.
• Optional: @copyright,@cite,@example,@code,@todo, @bug,@remark,@attention,@warning.
• Sample
  • Input: w3swldmd,
  • Output: w3swldmd.

PROGRAM

• Required

!> @brief  <one sentence description>      # contents of _1. Purpose_ from original header
!>
!> @details <extended description>          # contents of _2. Method_ from original header
!> 
!> @author <author name>  @date <dd-Mon-yyyy>

• Optional: @copyright,@cite,@example,@code,@todo, @bug,@remark,@attention,@warning.
• Sample
  • Input: w3grib,
  • Output: w3grib.

SUBROUTINE

• Required

!> @brief  <one sentence description>       # contents of _1. Purpose_ from original header
!>
!> @details <extended description>           # contents of _2. Method_ from original header
!>
!> @param[in/out] <param name> <very short description> # specify:  [in], [out], [inout], or just `@param`.
!> @author <author name>  @date <dd-Mon-yyyy>
!>

• Optional: @copyright,@cite,@example,@code,@todo, @bug,@remark,@attention,@warning.
• Sample
  • Input: w3dzxy(),
  • Output: w3dzxy().

FUNCTION

• Required

!> @brief  <one sentence description>
!> @param <param name>
!> @returns <return variable name>

• Optional: @author, @date, @details, @cite,@example,@code,@todo, @bug,@remark,@attention,@warning.
• Sample
  • Input: juldayt(),
  • Output: juldayt().

GLOBAL VARIABLES (inline documentation)

• Required

!<  <inline comment>

• Optional: N/A
• Sample
  • Input: ptmeth,
  • Output: w3odatmd.F90 see under section Variables: noge, idout, ptmeth, ptfcut.

Please also include the following information:

• Mention any labels that should be added:
  • documentation
• Are answer changes expected from this PR?
  • No. There are no changes to the repository at this point, only the acceptance of the templates is being considered.

Issue(s) addressed

• Please list any issues associated with this PR, including those the PR will fix/close.
  • This works towards addressing noaa-emc/ww3/issues/#547, though it will not close it. A separate PR with the actual markup to the source code will follow.

Commit Message

Accept doxygen templates.

Check list

• Branch is up to date with the authoritative repository (NOAA-EMC) develop branch.
• Checked the checklist for a developer submitting to develop.
• [na] If a version number update is required, checked the updating version number checklist.
• [na] If a new feature was added, a regression test for testing the new feature is added.

Testing

• How were these changes tested?
  • N/A. Only the templates are being formally accepted -- no changes to the repo at this time.
• Are the changes covered by regression tests? (If not, why? Do new tests need to be added?)
  • N/A.
• Have the matrix regression tests been run (if yes, please note HPC and compiler)?
  • N/A.
• Please provide the summary output of matrix.comp (matrix.Diff.txt, matrixCompFull.txt and matrixCompSummary.txt):
  • N/A.
• Please indicate the expected changes in the regression test output (Note the known list of non-identical tests).
  • N/A.
• Please provide the summary output of matrix.comp (matrix.Diff.txt, matrixCompFull.txt and matrixCompSummary.txt):
  • N/A.

[MatthewMasarik-NOAA]

Hello all, please review and make any suggestions or comments. We are planning for this to be open for community comments up until Friday, Jan 14th.

[edwardhartnett]

See in-line comments...

[edwardhartnett]

OK, I just noticed that you have a text description of your template for documentation. My comments to the code should also be applied to the template...

[edwardhartnett]

OK, I see you have this up on your own website. But GitHub provides a way to host your built documentation, called the gh-pages branch.

Here's how to do it:

1. build a copy of the documentation in your clone of the repo.
2. clone a new copy of the repo (an extra clone).
3. create a branch (in the extra clone) called 'gh-pages' and checkout gh-pages.
4. git rm -rf * (removes everything in the gh-pages branch)
5. copy the built documentation to the gh-pages directory: cp /build/html/* . (Where is the location of your first clone, where you built the docs.)
6. git add *
7. git commit -m "updated docs" -a && git push

Now your documentation will appear at: https://noaa-emc.github.io/WW3/. Put a link in your README.md. (See https://github.com/NOAA-EMC/NCEPLIBS-g2 for example.)

(The gh-pages feature also has to be turned on in the project settings for the repo.)

[edwardhartnett]

Looking real good! Do you want some help setting up the Doxyfile.in?

Also how do you handle version numbers? In the NCEPLIBS we have a file at the top level called VERSION which contains the version number. From there it is pulled in by the build system into the docs and the code.

[MatthewMasarik-NOAA]

Looking real good! Do you want some help setting up the Doxyfile.in?

Sure. If you guys have a way you tend to set them up I'm interested to hear. The file I've been working with is at: Doxyfile. I've made a few small recommended changes so far. Some settings like project brief, logo, etc. are left blank for the time being since we have not discussed content for them yet.

Also how do you handle version numbers? In the NCEPLIBS we have a file at the top level called VERSION which contains the version number. From there it is pulled in by the build system into the docs and the code.

We haven't discussed yet how we'd like to version the doxygen documentation so that's one of the fields we've left empty currently. That sounds like a clean solution though. I think were still nailing down the basic templates at this point and then we will get to some of the polishing like version numbers shortly after.

[edwardhartnett]

OK, can you move your Doxyfile to a subdirectory called "docs"?

Then, once you have committed these changes, I can submit a PR which turns the Doxyfile into Doxyfile.in, and causes CMake to generate the Doxyfile.

At that time we can add the VERSION file, and use it to store the software version. That's how the documentation can then be versioned...

[MatthewMasarik-NOAA]

OK, can you move your Doxyfile to a subdirectory called "docs"?

Then, once you have committed these changes, I can submit a PR which turns the Doxyfile into Doxyfile.in, and causes CMake to generate the Doxyfile.

At that time we can add the VERSION file, and use it to store the software version. That's how the documentation can then be versioned...

Yes. I'll make those changes after we have finalized our templates. This PR does not add any of the documentation, it's just to get developer agreement on doxygen headers.

[MatthewMasarik-NOAA]

A new PR which takes the headers from above, lists them in a markdown file, and adds them in a 'docs' folder has just been submitted, #585 . The new PR replaces this one. The new PR has no markup to the code, which is what I wanted for this initial submission.

[edwardhartnett]

Is this not going to be merged?

[MatthewMasarik-NOAA]

Hi @edwardhartnett , I closed this branch and added #585 in it's place. The reason is I had intended to initially just to get consensus on the headers, and not add any marked up code or documentation. #585 takes into account all the comments that had been made here, and put into the Header reference (./docs/ww3_doxy_tmpl.md). I also added an issue #586 that we will start incrementally committing marked up code and documentation. I apologize for making this PR a little more confusing than it needed to be, this was a learning experience for me. Note too that the issue #586 has the 'docs/' folder you requested, and has the Doxygen.in file inside as well, so if you had wanted to make a PR for changes to it please feel free.

[edwardhartnett]

OK, great! Good to see all this progress!

…

On Mon, Jan 24, 2022 at 6:33 AM Matthew Masarik ***@***.***> wrote: Hi @edwardhartnett <https://github.com/edwardhartnett> , I closed this branch and added #585 <#585> in it's place. The reason is I had intended to initially just to get consensus on the headers, and not add any marked up code or documentation. #585 <#585> takes into account all the comments that had been made here, and into the Header reference (./docs/ww3_doxy_tmpl.md). I also added an issue #586 <#586> that we will start incrementally committing marked up code and documentation. I apologize for making this PR a little more confusing than it needed to be, this was a learning experience for me. Note too that the issue #586 <#586> has the 'docs/' folder you requested, and has the Doxygen.in file inside as well, so if you had wanted to make a PR for changes to it please feel free. — Reply to this email directly, view it on GitHub <#562 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AJIOMMCH5F4JJOKODL32VX3UXVILDANCNFSM5KHOCYKA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[MatthewMasarik-NOAA]

Thank you, @edwardhartnett !