I think the real problem is the lack of conventions for adding metadata to
docstrings. I sorely miss `some-func/var' and SOME-PARAM from Emacs Lisp.
It's always
clear where you refer to other functions/variables and to parameters. This
makes it way easier to read (and parse) a docstring.
On 6 May 2015 at 14:17, Phillip Lord <phillip.l...@newcastle.ac.uk> wrote:
> <richard.mo...@posteo.de> writes:
> > The goal of this project is to develop a comprehensive and extensible
> > model for describing Clojure sources from an API perspective. I will
> > also write a program that analyses Clojure sources according to this
> > model and outputs data documenting their usage. This could be compared
> > to Javadoc, but emitting data to be consumed by other tools instead of
> > HTML. In order to foster adoption, I will provide extensive
> > documentation, including examples of such consumer tools, and
> > emphasize active communication with the community. ☙
>
> I would like to see a mechanism for structure in the clojure doc
> strings. So, consider the second definition in core.clj.
>
>
> (def
> ^{:arglists '([x seq])
> :doc "Returns a new seq where x is the first element and seq is
> the rest."
> :added "1.0"
> :static true}
>
> cons (fn* ^:static cons [x seq] (. clojure.lang.RT (cons x seq))))
>
> Analysing this further:
>
> Returns a new seq where x is the first element and seq is the rest.
>
> We have two uses of 'seq', where one refers to the general concept (or
> to the interface ISeq), and the other refers to the parameter defined in
> :arglists. We have 'x' which refers to an :arglists parameter also. And
> we have 'first', 'rest' and 'seq' none of which refer to the function
> names in the same namespace as cons. Although they might do if the doc
> string were reworded:
>
> Returns a new ISeq, s, where (first s) returns x and (rest s)
> returns seq.
>
>
> Not sure whether this is in scope or not, but it is about usage of
> metadata.
>
> Phil
>
> --
> 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.
>
--
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.
