Do you think language/API docs websites should support comments?
Pros: Adds context, familiar format, engages community
Cons: Can disincentivise contributions, comments might promote bad practices
I've only seen PHP and clojuredocs offer this.
miniblog.
Related Posts
110
Should lint suppressions be first class syntax or comments?
Adding a proper metadata system (e.g. Clojure or Rust) is a big design space but it's clear which expressions are affected.
Comments are much easier to implement but it's easy for users to get them wrong.
Thoughts?
65
I'm experimenting with diagnostics formatting.
* I've added a left margin, showing both the file name and line numbers
* I'm showing one line of context above/below the offending line.
* I'm using grey for comments.
What do you think? Is there anything you'd change?
8
Copilot doesn't offer a way of disabling completion inside comments. People have discovered a comical workaround: swearing in the comment!