Today, the only user-facing documentation I see among the Makefiles — Makefile and project.Makefile — is the set of lines echo-ed by the help target in Makefile:
Note: When I say "user" in this context, I'm referring to the person that would be running $ make commands.
Those lines are not necessarily written near where the associated target is defined.
That can result in the lines becoming stale (i.e. falling out of sync with the target). It can also result in that set of lines not accounting for newly-implemented targets (because those lines would be "out of sight, out of mind" when implementing a target).
Using that technique, a target's user-facing documentation would "live with" the target's definition. I think that will decrease the likelihood that the documentation falls out of sync with the target, and will increase the likelihood that new targets have user-facing documentation.
That technique can be extended to incorporate ANSI color codes, so that the output is in color. For example (this is a "quick and dirty" sed script):
Today, the only user-facing documentation I see among the Makefiles —
Makefile
andproject.Makefile
— is the set of linesecho
-ed by thehelp
target inMakefile
:https://github.com/linkml/linkml-project-cookiecutter/blob/d9b85bbbdcc49163416a3e3e18e23fe2ecce501b/%7B%7Bcookiecutter.project_name%7D%7D/Makefile#L60-L73
Those lines are not necessarily written near where the associated target is defined.
That can result in the lines becoming stale (i.e. falling out of sync with the target). It can also result in that set of lines not accounting for newly-implemented targets (because those lines would be "out of sight, out of mind" when implementing a target).
I propose that the Makefiles be updated to use a documentation technique like the one shown here: https://stackoverflow.com/a/47107132
Using that technique, a target's user-facing documentation would "live with" the target's definition. I think that will decrease the likelihood that the documentation falls out of sync with the target, and will increase the likelihood that new targets have user-facing documentation.
That technique can be extended to incorporate ANSI color codes, so that the output is in color. For example (this is a "quick and dirty" sed script):