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

Projects
None yet
3 participants
@tazjin
Contributor

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 some commits Oct 27, 2018

lib/trivial: Update function comments for doc generation
Expands on some of the function comments and add some of the
special syntaxes recognised by nixdoc.
lib/strings: Update documentation comments for doc generation
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
lib/lists: Update documentation comments for doc generation
Updates documentation comments with extra information for nixdoc[1]
compatibility.

[1]: https://github.com/tazjin/nixdoc
lib/debug: Update documentation comments for docs generation
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.
lib/options: Update documentation comments for docs generation
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

@tazjin tazjin referenced this pull request Oct 29, 2018

Merged

Call for Content: 2018/12 #69

@grahamc grahamc merged commit 0c5d9e5 into NixOS:master Oct 29, 2018

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

This comment has been minimized.

Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment