Update library function "docstrings" for nixdoc generation #49383
Motivation for this change
This extracts the changes to documentation comments that previously were in #49275 into a new pull-request. These changes should be backportable to 18.09.
Please see the other PR for more discussion, background information and examples of rendered documentation.
Expands on some of the function comments and add some of the special syntaxes recognised by nixdoc.
Updates documentation comments with extra information for nixdoc compatibility. Some documentation strings have additionally been reworded for clarity. "Faux types" are added where applicable, but some functions do things that are not trivially representable in the type notation used so they were ignored for this purpose. : https://github.com/tazjin/nixdoc
Updates documentation comments with extra information for nixdoc compatibility. : https://github.com/tazjin/nixdoc
Documents functions in `lib.debug` for docs generation with nixdoc. Note that type signatures and clearer descriptions are still missing on some of these functions, but this is good enough for a first run.
Documents functions in `lib.options` for docs generation with nixdoc. The formatting change in the `mkOption` arguments is due to the way `nixdoc` parses documentation comments on pattern arguments. It's not ideal, but it works.