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

Update library function "docstrings" for nixdoc generation #49383

Merged
merged 5 commits into from Oct 29, 2018

Conversation

@tazjin
Copy link
Member

@tazjin tazjin commented Oct 29, 2018

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.

Files covered:

  • lib/lists.nix
  • lib/strings.nix
  • lib/trivial.nix
  • lib/debug.nix
  • lib/options.nix

cc: @grahamc

tazjin added 5 commits Oct 27, 2018
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[1]
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.

[1]: https://github.com/tazjin/nixdoc
Updates documentation comments with extra information for nixdoc[1]
compatibility.

[1]: 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.
@tazjin tazjin requested review from edolstra, nbp and Profpatsch as code owners Oct 29, 2018
@grahamc grahamc merged commit 0c5d9e5 into NixOS:master Oct 29, 2018
9 checks passed
9 checks passed
grahamcofborg-eval ^.^!
Details
grahamcofborg-eval-check-meta config.nix: checkMeta = true
Details
grahamcofborg-eval-nixos-manual nix-instantiate ./nixos/release.nix -A manual
Details
grahamcofborg-eval-nixos-options nix-instantiate ./nixos/release.nix -A options
Details
grahamcofborg-eval-nixpkgs-manual nix-instantiate ./pkgs/top-level/release.nix -A manual
Details
grahamcofborg-eval-nixpkgs-tarball nix-instantiate ./pkgs/top-level/release.nix -A tarball
Details
grahamcofborg-eval-nixpkgs-unstable-jobset nix-instantiate ./pkgs/top-level/release.nix -A unstable
Details
grahamcofborg-eval-package-list nix-env -qa --json --file .
Details
grahamcofborg-eval-package-list-no-aliases nix-env -qa --json --file . --arg config { allowAliases = false; }
Details
@grahamc
Copy link
Member

@grahamc grahamc commented Oct 29, 2018

Please open a backport pr with git cherry-pick -x these,commit,hashes to the release-18.09 branch

@tazjin tazjin deleted the tazjin:docs/lib-docstrings branch Oct 29, 2018
@tazjin tazjin mentioned this pull request Mar 6, 2019
3 of 14 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants