I'm coming round to the view that optimum documentation is one web page per function.
This gives you space for prose, examples, related functions, version history and even user comments!
It's not the norm though, and requires substantial content writing.
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!