I would be so grateful and full of joy at the same time if I were to find this in our codebase

The downside is that it's fairly unreadable when rendered as some sort of IDE tooltip. Too long. Instead I'd create a (spec/malli) schema for each key, and add a "docstring" to each such key. (for Spec you'll need a custom solution - probably with Malli it's easier)

individual docstrings are also amenable to jump-to-definition e.g. I see a call to (convert ::convert/quality 100) , then I should be able to jump to the ::convert/quality keyword and see what it has attached (docstring, spec/schema, examples... whatever metadata you please)

If you do decide to use tables, if you use a github markdown compatible syntax, then tools like cljdoc will render them real pretty.

There's the fun middle ground of doing both, e.g. you document spec keys individually, and then programatically generate the table: (alter-meta #'convert assoc :doc (make-table-for ::convert-spec)) (cljdoc would pick it up since its analysis is runtime-based)

This table is great documentation(something for people to read), everything else proposed makes it worse documentation

It's not, it's a bunch of text that gets easily outdated. I've actually done this exact stuff for years (within team settings) Bunches of static text are best left for non-lisps - we know better.

Not saying anybody is wrong or right, but my personal preference is static docstrings. If I were to update a table in a docstring programatically, I'd do so on the original source and check that into version control, rather than updating docstrings at load time.

Cool thread! One consideration is that a cell in a markdown table can’t be multiple lines, so tables tend to get really wide. While many people don’t seem to care about that, standardizing on something that precludes reasonable line widths seemed underpowered, to me anyway. We still use tables when we feel like it, but well-formatted bulleted lists are my go-to for documenting keys and values, for now anyway.

Yeah @U01ERKW6F18 good point, I'll often start with a table and when it gets too wide, switch to a bulleted list.

The bulleted list can nest deeply too, which can be useful.

Given that Clojure vars can have arbitrary metadata associated with them, to me it seems like a missed opportunity to put structured information about code inside of a string.

https://danielgregoire.dev/posts/2021-10-15-clojure-src-test-meta/ I think this approach could be quite useful for separating “dev-time” metadata like structured examples from metadata actually needed at runtime when code is in production.

Shoot, I wanted to do something like metazoa and looks like someone beat me to the punch

Connect it with Clerk and we get something like Unison's view