Consider adding a specific code example to clerk/use-headers or clerk/table docstring?

[teodorlu]

Hi,

I recently tried making a Clerk table with headers without reading the Clerk book, only by reading docstrings. I wasn't able to understand what I was supposed to do.

Perhaps a specific example could help docstring readability?

Reading the docstrings

Clerk evaluated '/Users/teodorlu/dev/teodorlu/lab/src/learn/playwright_2.clj' in 416.38625ms.
user> (doc nextjournal.clerk/table)
-------------------------
nextjournal.clerk/table
([xs] [viewer-opts xs])
  Displays `xs` using the table viewer.

  Performs normalization on the data, supporting:
  * seqs of maps
  * maps of seqs
  * seqs of seqs

  If you want a header for seqs of seqs use `use-headers`.

  Supports an optional first `viewer-opts` map arg with the following optional keys:

  * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
  * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`
;; => nil
user> (doc nextjournal.clerk/use-headers)
-------------------------
nextjournal.clerk/use-headers
([xs])
  Treats the first element of the seq `xs` as a header for the table.

  Meant to be used in combination with `table`.
;; => nil

table refers to use-headers, and use-headers refers to table. But I don't understand what I should do from the docstrings.

Reading the book

Ah, OK. That makes sense!

Docstring change suggestion

Something like this:

(doc nextjournal.clerk/use-headers)
-------------------------
nextjournal.clerk/use-headers
([xs])
  Treats the first element of the seq `xs` as a header for the table.

  Meant to be used in combination with `table` like this:

      (clerk/table (clerk/use-headers [["odd numbers" "even numbers"]
                                       [1 2]
                                       [3 4]]))

I'm happy to make a PR if you want one.