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 [email protected]
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
[email protected]
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 [email protected].
For more options, visit https://groups.google.com/d/optout.
