shaunlebron
commented
8 years ago API format has been updated to reflect these new summaries. All syntax summaries have been written.
For the missing summaries of the normal API entries, we will just use the "Usage" + Docstring entries.
A function has a signature, which is automatically parsed into our docs.
Doc authors may sometimes want to rename args or replace the signature whole-sale with a format that's easier to understand for readers. This is the purpose of clojure's
^{:arglists ...}metadata and is the reason why our docfiles supported aSignaturesection.In practice, I've found that a single
Summarysection in our docfiles will give us the flexibility to choose what makes the most sense for certain entries. Sometimes we'll need multiple small signatures, which we want to annotate individually with comments. Othertimes, we'll need a longer form example. Also, syntax forms do not have signatures, so we need more flexibility there too.A summary section allows us to create a quick overview of a symbol however we want. Sometimes a signature fits, other times it won't. For undocumented symbols, we can auto-generate a summary using the signature and docstring.