An idea to improve foundations of documentation in clojure

[Sameer Rahmani]

Hi all.

First of all thanks all you guys because of Clojure/Clojurescript and all the fantastic tools and libraries around it. 

Certainly Clojure documentation needs an improvement. But to be honest there is no good tool in the community of Clojure or even any other communities to do that. Any tools out there has it's own pros and cons. 

Put the tooling aside writing documentation is not fun and there is no specific set of rules regarding to write docs in Clojure. IMO having a set of rules is not going to help us. What we need is a robust foundation which provides necessary means for tools and document generators or developers to write and generate decent documentation.

As all of you know Clojure.spec rocks. We already saw that the community quite love clojure.spec ( there might be some people not agree with me ). Since the first time I used spec in my code I was thinking that how awesome would it be for Spec to support documentation as well, and not just by adding strings to spec ( which would be the same as docstrings and not enought ). I was thinking, we can treat docs as data as well and include them in our specs in a certain way which allows developers and tools to use them in their own way. For example we can include more stuff in  `clojure.spec/fdef` in order to describe the function in question. Something like:

(s/fdef  some-fn 

         :args (....)

         :ret ....

         :fn ....

         :short-desc "some string which can be formatted using :args"

         :long-desc "some long description which may contains references and other stuff"

         :refrences [::other-fn]

         :other-necessary-keys-for-docs)

The above code is just a demonstration of what i had in mine. 

But this way we can describe the documentation of our code by data and it would be really easy for doc generators to fetch the spec of each symbol from spec registry and ask for the documentation data on that symbol and generate the documentation base on that data.

Also it would be easy for devs to write docs and specs would be a foundation and a practical set of rules to write docs. It is also backward compatible, because docstrings can live to fulfill their purpose and from now on we can start using this new feature to generate sophisticated docs . 

Describing documentation as data would help tools like cider and cursive to be more helpful as well.

I really like to know your thoughts on this topic.

At the end sorry for the long post and I'm not a native English speaker so there is a good chance that I did a bad job expressing my thoughts.

Cheers

Sameer

[Alex Miller]

Leaving aside what you want to do with it for the moment, we do plan to add docstrings for specs (http://dev.clojure.org/jira/browse/CLJ-1965) and I think generalized meta for spec is likely also a good idea (http://dev.clojure.org/jira/browse/CLJ-2194).

I don't know that adding extended docs to specs is any better than pushing more stuff into var meta. I think an independent, qualified-name-keyed repository is the best place to include additive information.