Indeed. I think Emacs docstrings are a bottom line -- Clojure should be
able to make these distinctions at least. And this would in turn allow
tools to use them. Why can I not click on function names in a docstring
and go to the function definition?
Phil
Bozhidar Batsov <bozhi...@batsov.com> writes:
> 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.
>>
--
Phillip Lord, Phone: +44 (0) 191 208 7827
Lecturer in Bioinformatics, Email: phillip.l...@newcastle.ac.uk
School of Computing Science,
http://homepages.cs.ncl.ac.uk/phillip.lord
Room 914 Claremont Tower, skype: russet_apples
Newcastle University, twitter: phillord
NE1 7RU
--
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.
