2023-04-13 Documentation team meeting notes #41


  • decide on new time for work meeting
  • updates
  • backlog grooming


New meeting time

  • 16:00 CEST Monday and Thursday

RFC 145

  • [RFC 0145] Doc-comments by hsjobeki · Pull Request #145 · NixOS/rfcs · GitHub
  • @hsjobeki:
    • Motivation: Want to differentiate between regular comments and doc comments, maybe have native Nix support in the future
    • Idea: Use markdown within the comment
    • Questions:
      • How to make the distinction?
      • What the rules should be inside?
    • @infinisil: Why ## over /** */`?
    • @fricklerhandwerk: nixdoc supports argument documentation which is single-line
      • @infinisil: Anti-feature IMO
      • @pennae: Argument docs how Hackage does it
      • @infinisil: Haskell has types to associate docs to, we don’t have that in Nix
        • we’d have to add documentation to the implementation, which doesn’t really work
          • e.g. { foo, ...}@args: mkDerivation args can’t properly get documentation for all arguments
  • @fricklerhandwerk: Most important task for the RFC: What problem we want to solve, which questions there are, how they can be answered, weighing the options
  • @pennae: Maybe start with type description language
    • @infinisil: We can incrementally make it stricter, first doc comments with freeform types, then strict types
    • @fricklerhandwerk: Incremental is good, we can even leave the markdown entirely freeform
    • @hsjobeki: Reserving headers for the future sounds useful
    • @fricklerhandwerk: Good patterns emerge from people using it
      • We already have patterns for types and examples
    • @hsjobeki: Reserve # Arguments?
      • @fricklerhandwerk: No pattern for that yet, should remove the section on reserved headers
    • @infinisil: Future work: Using the module system to render the type
    • @fricklerhandwerk: Then the type would be outside the doc comment
  • @pennae: Currently markdown would break the manual, also we need IDs
    • @fricklerhandwerk: Should be doable in nixdoc, might make it easier
    • @pennae: Actually not that trivial
    • @infinisil: Implementation detail, not very relevant for the RFC
    • @fricklerhandwerk: Should be noted in the RFC
    • @infinisil: Maybe the markdown should be very restricted at first.
      • It’s easier to first introduce a new feature with strictness, then make it less strict as time goes on
        • general agreement
  • Discussion about whether section headers and contents should be restricted
  • (didn’t take notes for a while)
  • Outcomes:
    • free-form documentation comment, type annotation, and examples are distinct data structures
      • should define represenation and semantics separately, not lump together in a markdown comment
      • type annotation should probably instead introduced to the Nix language in one way or another
      • examples should be structured data, too, in order to allow for automatic testing
    • doc comment should just be free form text
      • RFC 64 justifies tying it to markdown
    • specify scope for which doc comments apply, and provide rationale for decision
      • maybe only for bindings
      • functions can also be written without a name just top-level in a file though
    • the RFC should be limited to the free form doc comment, and leave the rest for future work

Action Items

  • @spacekookie: Tutorials and explanation for module system
  • @infinisil: Reference docs for module system
  • @hsjobeki: Capture discussion outcomes in RFC alternatives and arguments
1 Like