I am very happy with @martinklepsch cljdoc, and I was wondering if there were some best practices for how to write documentation. I saw https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc but I was wondering if there was a way to effectively document a namespace (why does it exist? what should be here?) and not just its vars.
Another small annoyance I have is that the README from Github always seems to come from an earlier version…
Yeah this is a little annoying indeed. The reason probably is that you didn’t update your README (and committed those changes) before you pushed the release to Clojars.
The revision at which files are shown is based on the artifact that’s pushed to Clojars and usually deployment tools provide the SHA of HEAD as git revision. So if you publish a release and then update your README to mention the newer version in a subsequent commit that commit will not be used as it wasn’t HEAD at the time of publishing.
Hope this makes sense. We should probably mention this in the guide as well.
You can put markdown in a namespace docstring and basically provide any additional information. I’m not aware of any conventions in that regard but long namespace docstrings are rendered beautifully in cljdoc and it always makes me happy to see them 
(I saw a few but can’t recall a specific example.)
Thanks - they work indeed. Are all descriptions rendered as Markdown?
All docstrings are rendered as markdown, yes.
Just stumbled upon this discussion again and since we talked about it I also wrote a little post detailing a few more things you can do to have killer docstrings:
https://www.martinklepsch.org/posts/writing-awesome-docstrings.html
This topic was automatically closed 182 days after the last reply. New replies are no longer allowed.