I've adopted:
(defn create-session!
"Create shared sessions and their associated channel.
Arguments:
some-req-arg - a vector, something descriptive.
[session-id] - a String, the session's identifier. [auto-generated
UUID]
Returns:
m - a MapEntry, the stored session
Notes:
If the session already exists, it is returned."
Examples:
(create-session! [1 2]) => ["123456" {:ch channel, :user-count 1}]
{:added "0.1.0"}
...)
I find this format looks nice with docs generated from autodoc, and
requires some formatting for marginalia (put everything from
"Arguments:", down, into a code block format. Maybe split off Notes
and Examples into their own blocks). If you're going to be generating
your primary documentation with marginalia, I suggest going with a
free-text narrative of the function, including examples, for your doc
string.
Paul
On May 13, 1:23 pm, Stuart Sierra <[email protected]> wrote:
> Hi Ralph,
>
> There's no established idiom beyond the guidelines
> athttp://dev.clojure.org/display/design/Library+Coding+Standards
>
> I am not aware of any tool that parses Clojure docstrings for Javadoc-style
> "@param" and "@return", although I would like to see that happen.
>
> For now, Clojure docstrings are just plain text.
>
> -Stuart Sierra
> clojure.com
--
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
