[RFC 0145] Doc-comments #145
Conversation
There was a problem hiding this comment.
I approve a large part of this, but it looks very hastily written. with some grammatical mistakes and self-contradictions.
I would suggest structural revisions too. Most people will read it top to bottom. Please introduce the basics first (eg that you suggest multiple alternatives) to make the proposal easier to understand.
Thanks for your feedback. I wanted to include the community at early stage to gather feedback. I'm sorry if it is not cleaned up yet. I'll fix this asap to avoid confusion. |
|
@figsoda, do you want to be the RFC co-author? I would be delighted if somebody assisted with those efforts. |
I don't have the time capacity currently, but I will keep my options open for now |
|
I have seen it. But it can take time to adapt to the nix ecosystem. |
|
@AndersonTorres doc generation for nixpkgs has been tried multiple times (also by me). I am not sure if you are referencing doxygen in a positive, or negative light in this comment. The main issue with CFG-based doc generators is that
In my opinion, a docgenerator will need to parse and possibly evaluate files. state of the art (SOTA) is currently nixdoc, maintained before by tazjin. As the RFC also states, it is used to generate docs for things in |
Co-authored-by: figsoda <[email protected]>
Doxygen is the "de facto" standard for doc-comments (I think so). It would be a good starting point - regardless if we decide by not using their tooling.
The same amount as C++ -
Like C (supported by Doxygen)?
Like
As I have said in other RFC, it would augment the not-yet-formalized Nixlang. |
Doxygen may inspire the C++ and Java worlds. Although it is a great tool, I think we should extend the existing solution Rust's excellent markdown docstring syntax mainly inspired this RFC. We should mainly look at Rustdocs' approaches if we want to use markdown similarly. https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html (I didn't say not to look into Doxygens ways) |
|
OK, you are using rustdoc. |
|
so the second FCP has ended again and from reading through the comments I couldn't find any blocking comments. If I'm mistaken and overlooked a comment please tell me. Otherwise I would suggest the steering committee to merge this RFC on the next occasion. |
|
This RFC is approved! |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/contribute-to-the-nix-2023-recap/37484/3 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2024-01-04-documentation-team-meeting-notes-102/37754/1 |
|
Is there a tracking issue for the implementation of this RFC? |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2024-02-15-documentation-team-meeting-notes-109/39826/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/tweag-nix-dev-update-54/39990/1 |
Co-authored-by: figsoda <[email protected]> Co-authored-by: Anderson Torres <[email protected]> Co-authored-by: gilice <[email protected]> Co-authored-by: Florian Klink <[email protected]> Co-authored-by: Mykola Orliuk <[email protected]> Co-authored-by: asymmetric <[email protected]> Co-authored-by: Lassulus <[email protected]> Co-authored-by: Robert Hensing <[email protected]> Co-authored-by: Silvan Mosberger <[email protected]> Co-authored-by: Adam Joseph <[email protected]>
For a long time `nix repl` has supported displaying documentation set on builtins, however, it has long been convention to use Markdown comments on Nix functions themselves for documentation. This exposes that information to `nix repl` users in a nice and formatted way. NixOS/rfcs#145 doc-comments are primarily what this feature is intended to consume, however, support for lambda documentation in the repl is experimental. We do our best effort to support the RFC here. These changes are based on [the nix-doc library](https://github.com/lf-/nix-doc) and are licensed under the terms described in the relevant source files. Change-Id: Ic6fe947d39a22540705d890737e336c4720b0a22
For a long time `nix repl` has supported displaying documentation set on builtins, however, it has long been convention to use Markdown comments on Nix functions themselves for documentation. This exposes that information to `nix repl` users in a nice and formatted way. NixOS/rfcs#145 doc-comments are primarily what this feature is intended to consume, however, support for lambda documentation in the repl is experimental. We do our best effort to support the RFC here. These changes are based on [the nix-doc library](https://github.com/lf-/nix-doc) and are licensed under the terms described in the relevant source files. Change-Id: Ic6fe947d39a22540705d890737e336c4720b0a22
|
Since this was merged, please someone mark this as accepted. @GetPsyched (the last one I remember with labeling rights) |
GetPsyched
added
status: accepted
and removed
status: FCP
|
Thanks for the reminder. Must've been missed at the time. Fixed. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2024-07-08-nix-team-meeting-minutes/49099/1 |
Find a common sense for doc-comments.
What does a doc-comment look like?
The current Nix language doesn't offer doc comments. There is a vague convention that is not satisfying if you want to build reliable tooling.
See rendered rfc here
Why this matters
Various previous PRs and issues tried of finding a solution to automatic API documentation of nix code.
:doccommand to nix repl nix#3904(Are the most relevant i think)
I think NixOS/nix#1652 is the best approach (yet) which also avoids runtime overhead. Unfortunately the maintainer of this PR couldn't manage to find a solution that satisfies all different opinions within the nix community, and thus it never got merged. I'd like to pick up the discussion on documentation again in this RFC format to find an agreement on a usable doc-comment format that satisfies the important need of having documentation.
This RFC is not going to discuss how to write good documentation, or how to style your code or your comments. It outlines the fundamentals that are necessary to integrate doc-comments into the language. Anything beyond that it out of scope for this RFC.
I also developed noogle. Noogle finds expressions and their documentation with the currently inoffical format for doc-comments. — Attempts to extend the scope to discover automatically and index more parts of nixpkgs failed due to a missing standard doc-comment format.
I'm highly convinced It would be possible to build automatic documentation for code with a standard format. Like in any other major ecosystem (e.g. Rust/C++/Go/Js/...).
Update
With support from one of our POCs in nix. I set-up a demo website for reference documentation. Showing the potential impact of doc-comments