Proposal: go through each non-customized official doc, and format it with humane paragraphs

[vemv]

Sometimes the official clojure.core docs are self-explanatory -needing no custom docs- but are formatted awfully, without newlines to delimit paragraphs.

I'm wondering if someone at Grimoire could volunteer (I do!), go through each of those and create a doc which is identical, except for a few interspersed \ns.

I'm aware that from a technical perspective, having only-slightly-different docs can be problematic, since the modified one could get out of sync with the original one (i.e. the original adds a few new words, now we don't know if the modified copy is a totally-original text, or just an outdated 'newline adaptation').

But then one could compare (remove #{\n} original) vs (remove #{\n} modified) for detecting which custom Grimoire docs are just "newline adaptations", making them apt for being automatically updated.

WDYT?

[vemv]

Example of a perceivedly unreadable one:

Takes a set of predicates and returns a function f that returns true if all of its
composing predicates return a logical true value against all of its arguments, else it returns
false. Note that f is short-circuiting in that it will stop execution on the first
argument that triggers a logical false result against the original predicates.

I'd insert \n\n before Note that f [...].

[arrdem]

Rendering docstrings is an obnoxious and finicky task at best. Since there's no standardized docstring tooling, everyone (myself included) has their own markup conventions. Some libraries use full Markdown, others bits of wiki-style notation, and most are just formatted as plain text which is really the worst of all possible worlds when it comes to displaying in a browser or richer content environment. Core especially is just a bunch of hand-formatted plain text.

I'd rather limit the use of notes (hand-written docstrings) to more meaningful docs than just the formated docstring wherever possible. That said, I acknowledge that there are absolutely user docs in the live Grimoire instance which are little better than the official docstring formatted into Markdown.

On this particular issue, I've already got a snippet from another project which could be useful -

(defn strip-leading-space
  "Docstrings are hard to format in part because sometimes they have a
  whole lot of leading whitespace.
  This function tries to take an arbitrary docstring and chomp off the
  minimum amount of COMMON whitespace from every line."
  [docstring]
  (as-> docstring %
    ;; Delete any leading whitespace and newlines
    (str/replace % #"\A[\s\n\r]+" "")
    (str/split-lines %)
    (rest %) ;; First line is always different
    ;; Count leading whitespace
    (keep (fn [l]
            (if-let [match (re-find #"^\s+" l)]
              (count match)))
          %)
    ;; Common is the minimal leading substring
    (apply min 1000 %)
    (format "(?ms)^[\\s&&[^\n\r]]{%s}" %)
    (re-pattern %)
    (str/replace docstring % "")))

This isn't something I'm working on actively, but if you wanted to patch that into Grimoire and QA that it didn't really mess up rendering any of the docstrings (clojure.pprint for instance has plain-text tables if I recall) I'd be happy to get it merged and deployed.

[vemv]

Since there's no standardized docstring tooling, everyone (myself included) has their own markup conventions. Some libraries use full Markdown, others bits of wiki-style notation, and most are just formatted as plain text which is really the worst of all possible worlds when it comes to displaying in a browser or richer content environment.

Thanks for showing me the broader perspective!

On this particular issue, I've already got a snippet from another project which could be useful

In my second comment (prior to editing it) I made the mistake of including leading whitespace which wasn't my real concern (although it can be). It's the lack of newlines what I find the most unreadable.

Does that make a difference on your opinion?

[arrdem]

It doesn't make a difference to me - ideally Grimoire's docstring rendering would be able to eat "arbitrary" text and generate something which could at least be divided into clear paragraphs and preformatted text so that paragraphs can just be <p> elements that get flowed by the browser.

The snippet I provided is used in one of my other projects to take docstrings and get them into a form where at least a large category of unstructured text can be treated as "close enough" to Markdown to just throw into a Markdown processor and let better formatted text / HTML come out the other side.

[vemv]

ideally Grimoire's docstring rendering would be able to eat "arbitrary" text and generate something which could at least be divided into clear paragraphs and preformatted text so that paragraphs can just be <p> elements that get flowed by the browser.

Guessing where paragraph delimiters should be inserted seems a rather hard problem (and one that strip-leading-space doesn't seem to address)...