search

hafs-community / HAFS

Hurricane Analysis and Forecast System
Other
29 stars 52 forks source link

Improve the documentation blocks in HAFS ex-script and ush scripts #236

Open BinLiu-NOAA opened 8 months ago

BinLiu-NOAA commented 8 months ago

Description

Provide a clear and concise description of the requested feature/capability. From NCO SPA: Improve the documentation blocks in HAFS ex-script and ush scripts since there are many ex-scripts and ush scripts don't have documentation blocks. Please add these blocks as described in “NCO WCOSS Implementation Standards”,page 13 -

x. Documentation Blocks Source code and scripts must be annotated with information that may help staff remedy a problem if something goes awry. In some cases, too much information is as bad as none at all. We ask that you use your best judgment to include information that will be of the most help in troubleshooting potential issues. Example 4 shows a suggested format for a documentation block (DOCBLOCK).

Please improve the following scripts with Documentation Blocks at next upgrade - scripts/exhafs_analysis.sh scripts/exhafs_atm_ic.sh scripts/exhafs_atm_lbc.sh scripts/exhafs_atm_post.sh scripts/exhafs_atm_prep.sh scripts/exhafs_atm_vi.sh scripts/exhafs_atm_vi.sh.new scripts/exhafs_atm_vi.sh.org scripts/exhafs_datm_prep.sh scripts/exhafs_docn_prep.sh scripts/exhafs_emcgraphics.sh scripts/exhafs_forecast.sh scripts/exhafs_gempak.sh scripts/exhafs_hrdgraphics.sh scripts/exhafs_merge.sh scripts/exhafs_msg_check.py scripts/exhafs_obs_prep.sh scripts/exhafs_ocn_post.py scripts/exhafs_ocn_prep.py scripts/exhafs_output.sh scripts/exhafs_product.sh scripts/exhafs_unpost.sh scripts/exhafs_wav_post.py scripts/exhafs_wav_prep.py

ush/cdeps_utils/hafs_era5_prep.sh ush/cdeps_utils/hafs_esmf_mesh.py ush/cdeps_utils/hafs_ghrsst_prep.sh ush/cdeps_utils/hafs_oisst_prep.sh ush/cdeps_utils/hafs_rtofs_prep.sh

ush/hafs_atparse.sh ush/hafs_make_orog.sh ush/tcutil_interpolate.py

Proposed solution

How should the new feature/capability be added? If you have thoughts on the implementation strategy, please share them here.

Status (optional)

Do you (or a colleague) plan to work on adding this feature?

Related to (optional)

Directly reference any related issues or PRs in this or other repositories, and describe how they are related. Examples:

BinLiu-NOAA commented 4 months ago

Documentation blocks have been added/improved for HAFS ex-scripts (see 8af655e) and ush scripts (see a5740d3).

BinLiu-NOAA commented 3 months ago

Additional comments from NCO regarding the ex-script and ush script documentation blocks recently added:

"Script name, author and abstract are included. However, the example in the standards document has a much more complete documentation block... including...

It's very important to know the usage of a given script as well as the potential error conditions."

And here is the response to these additional comments through the Bugzilla thread: "As we work toward the next HAFS upgrade, we will keep improving the documentation blocks for the HAFS ex-script and ush scripts by adding these above-mentioned sections (where applicable)."