Tips for using marginalia
I've used Marginalia a tiny bit for a few of the libraries I've developed that actually have comments and doc strings.
Marginalia did help me refine my doc strings and comments. From the Marginalia docs:
Following the guidelines will work to make your code not only easier to follow --- it will make it better. The very process of using Marginalia will help to crystalize your understanding of problem and its solution(s).
In general, this is true. Marginalia follows some strict rules, like a compiler. Even if your comments seem to make sense to you reading the source, Marginalia might produce something that makes no sense. However, it generates attractive and useful documentation. So I decided to use it.
What this meant was figuring out some of the quirks of Marginalia. Here is what I've learned:
Don't use ;-comments when a doc string is more appropriate
This is good advice in general and Marginalia makes the comments look wrong. In Marginalia, comments seem to follow the docstring for the function they apply to when both are defined.
Blank lines are important
From what I can tell, a blank line will cause the top-level comment to be placed above the following form. No blank line will put them at the same level. That sounds very sensible.
However, if you have a comment with no blank line immediately before a function, the docstring for that function will come first, followed by the comment. This is weird. You should follow the advice above and choose docstring or comments, but not both.
Namespace ordering
There is a convention in Clojure to use project.core as the main namespace of a library. Marginalia sorts the namespaces alphabetically. This means that in the documentation, project.anunimportantmodule comes before project.core.
I have renamed my namespaces once to avoid this problem. But in general, my projects are very small and don't have many namespaces. It's not a practical problem.
Marginalia is great. It produces beautiful documentation. And it has helped me clarify my code.
Nice job.