Re: An idea to improve foundations of documentation in clojure

[James Reeves]

A better place for this is on the var's metadata, which is where the docstring, arglist, etc. are already stored.

On 17 October 2017 at 20:16, Sameer Rahmani <lxsa...@gmail.com> wrote:

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

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+unsubscribe@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

James Reeves

booleanknot.com