Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Standardize documentation in `Utilities` scripts #796
However, many of the lack a proper documentation. There is some truth in that only a limited number of people (mainly maintainers) use them effectively, but even then, it may be worthwhile properly documenting them.
If they followed some standard, the documentation could be rendered on a web page, much like the Doxygen class documentation, and thus the purpose and use of the scripts would be accessible. That would allow for a more effective information hand-off to new maintainers, or other community members could be aware of such scripts to apply them in some parts of the toolkit (e.g. remotes, third parties, etc.).
Proper/canonical script documentation (both header-like comment and usage help message, following some documentation standard if possible, e.g.:
having some mandatory sections/fields:
With a result that could look like:
If this is something that could be automated, it would be nice. Otherwise, it will need to be done manually.
Also, if this is made effective, the ITK Software Guide will need to contain a section dedicated to documenting how the bash scripts and their usage needs to be ideally written (
Maintenance scripts lacking proper documentation and/or no standards followed to document scripts.
If the commit number is required, run