[RFC 0145] Doc-comments #145

hsjobeki · 2023-03-29T09:49:57Z

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.

nix repl: Provide documentation from comment when evaluating to lambda nix#1652
Support documentation on functors nix#5527
Feature: add :doc command 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

gilice

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.

rfcs/0145-doc-strings.md

hsjobeki · 2023-03-29T15:31:56Z

art of this, but it looks very hastily written. with some grammatical mistakes and self-contradictions.

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.

rfcs/0145-doc-strings.md

Co-authored-by: figsoda <[email protected]>

hsjobeki · 2023-03-29T16:53:05Z

@figsoda, do you want to be the RFC co-author? I would be delighted if somebody assisted with those efforts.
And you already helped a lot. 👍

figsoda · 2023-03-29T17:09:25Z

@figsoda, do you want to be the RFC co-author?

I don't have the time capacity currently, but I will keep my options open for now

hsjobeki · 2023-03-30T07:00:00Z

I have seen it. But it can take time to adapt to the nix ecosystem.
This could be a tool (??) after we introduce doc-strings. Until now, there are just comments. Even if Doxygen would understand nix, it could see only non-informative internal comments that don't help to lower the entry barrier.
There is no way to syntactically and visually use a comment for doc-strings. If you have any suggestions here, I am happy to hear them. So go ahead and let us hear your criticisms :)

gilice · 2023-03-30T07:07:04Z

@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

nix has multiple forms of comments
there isn't a simple function keyword
attributes would be also needed to be documented.

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 lib

Co-authored-by: figsoda <[email protected]>

AndersonTorres · 2023-03-30T11:55:03Z

I am not sure if you are referencing doxygen in a positive, or negative light in this comment.

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 main issue with CFG-based doc generators is that

nix has multiple forms of comments

The same amount as C++ - /* multiline */ and # single line. Both are supported by Doxygen.

there isn't a simple function keyword

Like C (supported by Doxygen)?

attributes would be also needed to be documented.

Like @param?

In my opinion, a docgenerator will need to parse and possibly evaluate files.

As I have said in other RFC, it would augment the not-yet-formalized Nixlang.
I think this is too complicated in general, and too complicated to just implement doc-comments in particular.

hsjobeki · 2023-03-30T13:23:06Z

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.

Doxygen may inspire the C++ and Java worlds. Although it is a great tool, I think we should extend the existing solution nixdoc

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)

AndersonTorres · 2023-03-30T16:02:38Z

OK, you are using rustdoc.
I know the Nix RFCs don't mandate/require extra sections, but it would be good to include a last section, "References", including links to the things you are referring to.

Lassulus · 2023-11-21T19:54:16Z

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.

kevincox · 2023-11-29T14:32:16Z

This RFC is approved!

nixos-discourse · 2023-12-30T00:22:34Z

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

nixos-discourse · 2024-01-04T16:22:58Z

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

Qyriad · 2024-01-23T01:39:22Z

Is there a tracking issue for the implementation of this RFC?

nixos-discourse · 2024-02-15T16:24:45Z

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

nixos-discourse · 2024-02-19T10:25:36Z

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

AndersonTorres · 2024-07-14T13:45:15Z

Since this was merged, please someone mark this as accepted.
Or there something to be decided still?

@GetPsyched (the last one I remember with labeling rights)

GetPsyched · 2024-07-15T08:34:26Z

Thanks for the reminder. Must've been missed at the time. Fixed.

nixos-discourse · 2024-07-15T11:23:27Z

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

nixos-discourse · 2024-11-07T18:02:28Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-11-23-24-zhf-24-11-hackathon-ost-zurich-rapperswil-jona/51634/3

hsjobeki added 2 commits March 29, 2023 11:42

init: rfc about docs-string format

af461dd

init: rfc number

dee60aa

gilice reviewed Mar 29, 2023

View reviewed changes

fix some major spelling issues

4508831

figsoda reviewed Mar 29, 2023

View reviewed changes

rfcs/0145-doc-strings.md Outdated Show resolved Hide resolved

figsoda reviewed Mar 29, 2023

View reviewed changes

rfcs/0145-doc-strings.md Outdated Show resolved Hide resolved

figsoda reviewed Mar 29, 2023

View reviewed changes

rfcs/0145-doc-strings.md Outdated Show resolved Hide resolved

figsoda reviewed Mar 29, 2023

View reviewed changes

rfcs/0145-doc-strings.md Outdated Show resolved Hide resolved

figsoda reviewed Mar 29, 2023

View reviewed changes

rfcs/0145-doc-strings.md Outdated Show resolved Hide resolved

hsjobeki and others added 4 commits March 29, 2023 18:35

gramatical cleanup

34bf50e

gramatical cleanup

130d9e5

fix: consistent naming: doc-string(s)

ab0aa26

Update rfcs/0145-doc-strings.md

2b0dea2

Co-authored-by: figsoda <[email protected]>

hsjobeki added 3 commits March 29, 2023 19:02

make statement more clear

a3ee89a

add statement what a sections is

e1a7475

remove empty example

d7e0cf5

hsjobeki and others added 2 commits March 30, 2023 09:29

Update rfcs/0145-doc-strings.md

4d69893

Co-authored-by: figsoda <[email protected]>

add: more examples, explanations

b4a1297

hsjobeki added 2 commits March 30, 2023 14:50

Update 0145-doc-strings.md

f6bd84f

Update 0145-doc-strings.md

4d2329a

hsjobeki changed the title ~~init: rfc about docs-string format~~ [RFC 0144] Docstrings Mar 30, 2023

hsjobeki changed the title ~~[RFC 0144] Docstrings~~ [RFC 0145] Docstrings Mar 30, 2023

infinisil mentioned this pull request Nov 20, 2023

lib: Take advantage of section descriptions NixOS/nixpkgs#268619

Merged

1 task

kevincox merged commit c65c832 into NixOS:master Nov 29, 2023

kevincox mentioned this pull request Nov 29, 2023

Meeting 2023-11-29 NixOS/rfc-steering-committee#134

Closed

10 tasks

adamcstephens mentioned this pull request Dec 30, 2023

doc: improve documentation for trivial text writing functions NixOS/nixpkgs#277534

Merged

13 tasks

infinisil mentioned this pull request Jan 8, 2024

feat: Introduce digging behaviour nix-community/nixdoc#98

Draft

hsjobeki mentioned this pull request Jan 12, 2024

nixos-render-docs: cannot render commonmark NixOS/nixpkgs#280514

Closed

piegamesde mentioned this pull request Feb 7, 2024

[RFC 0166] Nix formatting, take two #166

Merged

infinisil mentioned this pull request Feb 27, 2024

Example syntax in comments nix-community/nixdoc#6

Closed

This was referenced Feb 27, 2024

String type hint NixOS/nix#10099

Open

Inline docstring support NixOS/nix#228

Open

roberth mentioned this pull request May 13, 2024

Add cheat sheets NixOS/marketing#7

Merged

fricklerhandwerk mentioned this pull request May 17, 2024

Nested block comments NixOS/nix#10730

Closed

roberth mentioned this pull request Jul 9, 2024

Doc comments NixOS/nix#11072

Merged

GetPsyched added status: accepted and removed status: FCP in Final Comment Period labels Jul 15, 2024

inclyc mentioned this pull request Jul 28, 2024

emacs: teach elisp builders the finalAttrs pattern NixOS/nixpkgs#330589

Merged

13 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC 0145] Doc-comments #145

[RFC 0145] Doc-comments #145

hsjobeki commented Mar 29, 2023 •

edited

Loading

gilice left a comment •

edited

Loading

hsjobeki commented Mar 29, 2023 •

edited

Loading

hsjobeki commented Mar 29, 2023 •

edited

Loading

figsoda commented Mar 29, 2023

hsjobeki commented Mar 30, 2023 •

edited

Loading

gilice commented Mar 30, 2023 •

edited

Loading

AndersonTorres commented Mar 30, 2023

hsjobeki commented Mar 30, 2023 •

edited

Loading

AndersonTorres commented Mar 30, 2023

Lassulus commented Nov 21, 2023

kevincox commented Nov 29, 2023

nixos-discourse commented Dec 30, 2023

nixos-discourse commented Jan 4, 2024

Qyriad commented Jan 23, 2024

nixos-discourse commented Feb 15, 2024

nixos-discourse commented Feb 19, 2024

AndersonTorres commented Jul 14, 2024

GetPsyched commented Jul 15, 2024

nixos-discourse commented Jul 15, 2024

nixos-discourse commented Nov 7, 2024

[RFC 0145] Doc-comments #145

[RFC 0145] Doc-comments #145

Conversation

hsjobeki commented Mar 29, 2023 • edited Loading

Find a common sense for doc-comments.

See rendered rfc here

Why this matters

Update

gilice left a comment • edited Loading

Choose a reason for hiding this comment

hsjobeki commented Mar 29, 2023 • edited Loading

hsjobeki commented Mar 29, 2023 • edited Loading

figsoda commented Mar 29, 2023

hsjobeki commented Mar 30, 2023 • edited Loading

gilice commented Mar 30, 2023 • edited Loading

AndersonTorres commented Mar 30, 2023

hsjobeki commented Mar 30, 2023 • edited Loading

AndersonTorres commented Mar 30, 2023

Lassulus commented Nov 21, 2023

kevincox commented Nov 29, 2023

nixos-discourse commented Dec 30, 2023

nixos-discourse commented Jan 4, 2024

Qyriad commented Jan 23, 2024

nixos-discourse commented Feb 15, 2024

nixos-discourse commented Feb 19, 2024

AndersonTorres commented Jul 14, 2024

GetPsyched commented Jul 15, 2024

nixos-discourse commented Jul 15, 2024

nixos-discourse commented Nov 7, 2024

hsjobeki commented Mar 29, 2023 •

edited

Loading

gilice left a comment •

edited

Loading

hsjobeki commented Mar 29, 2023 •

edited

Loading

hsjobeki commented Mar 29, 2023 •

edited

Loading

hsjobeki commented Mar 30, 2023 •

edited

Loading

gilice commented Mar 30, 2023 •

edited

Loading

hsjobeki commented Mar 30, 2023 •

edited

Loading