Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix doxygen in AVIATION.f #395

Merged
merged 8 commits into from
Oct 6, 2021
Merged

Fix doxygen in AVIATION.f #395

merged 8 commits into from
Oct 6, 2021

Conversation

edwardhartnett
Copy link
Collaborator

@edwardhartnett edwardhartnett commented Sep 25, 2021

Part of #392

In this PR I fix the doxygen in the file AVIATION.f, to eliminate doxygen warnings for that file.

I cannot fix all your legacy documentation - this is just a sample to show how it should be done. ;-)

Some things to note for doxygen conversion:

  • Efforts to align text in the comments with extra spaces are not needed and shouldn't be attempted. Doxygen reformats the text nicely, so all whitespace is ignored by doxygen.
  • Extra documentation elements like "ABSTRACT", "INPUT PARAMETERS", "USAGE", and others can all be removed.
  • Doxygen automatically finds all the functions that have been called by, and all the functions calling, a subroutine, so no need to attempt to document these manually.
  • Last line of doxygen docblock has author and date.
  • First sentence of each subroutine/function documentation block is important: it is the "brief description" of the function. It should be a complete sentence, with description of the function, properly punctuated.

In general, punctuation is missing from much of the documentation. Fortran programmers apparently are trying to save on keystrokes by refraining from putting a period on the end of the sentences. ;-) That's not good. Documentation should be punctuated properly to aid understanding.

@WenMeng-NOAA
Copy link
Collaborator

@fossell Would you please review the PR? Thanks!

@fossell
Copy link
Contributor

fossell commented Sep 29, 2021

@edwardhartnett - Thanks for providing this an example of porting to doxygen syntax and standards. We will use this as guidance to translate other routines as well.

@WenMeng-NOAA - This PR is just comment changes that Ed has provided as an example for doxygen. I have not tested this PR, just visually inspected. Only comments were changed in the routine, but if you want to run RTs to ensure no issues that's ok, either way is fine with me.

@WenMeng-NOAA
Copy link
Collaborator

@edwardhartnett Could you sync your branch with upstream/develop? Thanks!

@WenMeng-NOAA WenMeng-NOAA added Ready for Review This PR is ready for code review. No Baseline Change No baseline of the UPP regression tests are made. documentation Improvements or additions to documentation labels Oct 5, 2021
@edwardhartnett
Copy link
Collaborator Author

@WenMeng-NOAA I have synced branch...

@WenMeng-NOAA
Copy link
Collaborator

@edwardhartnett Do you have an UPP issue linking to this PR?

@edwardhartnett
Copy link
Collaborator Author

@WenMeng-NOAA this relates to issue #392.

@WenMeng-NOAA
Copy link
Collaborator

@fossell With this PR merged, would DTC put efforts to solve the list of warnings in issue #392?

@WenMeng-NOAA WenMeng-NOAA merged commit 9f5f788 into develop Oct 6, 2021
@edwardhartnett edwardhartnett deleted the ejh_aviation branch October 6, 2021 14:01
EricJames-NOAA pushed a commit to EricJames-NOAA/UPP that referenced this pull request Dec 14, 2022
…uld be the same as FV3_HRRR except for DT_ATMOS, dt_inner, and imfdeepcnv. (NOAA-EMC#395)

This update also avoids some NA 13km FV3 crashes.
Contributions from Tanya/Joe/Ming.  
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation No Baseline Change No baseline of the UPP regression tests are made. Ready for Review This PR is ready for code review.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants