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 <lxsame...@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 clojure@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+unsubscr...@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+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/d/optout. > -- James Reeves booleanknot.com -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
