On Sunday, January 13, 2013 1:03:35 PM UTC-5, Marcel Möhring wrote:
>
> Hello,
>
> is there a better way to document a function if I want to include type
> information
> and parameters for in/out?
>
> Currently I am using this approach but it feels rather clumsy:
>
> "Takes a screen and a pixel coordinate and returns
> a map of maps with pixel colors
> and adjusted pixel coordinates around the pixel.
> Directions are degree numbers from 0 to 315.
> in: screen (BufferedImage), x (Number), y (Number)
> out: map of maps ({direction (Number) {:color (Number) :x (Number)
> :y (Number)}})"
>
> Are there any better ways?
>
>
I'd add some whitespace and format that docstring in markdown:
~~~
"Takes a screen and a pixel coordinate and returns a map of maps with
pixel colors and adjusted pixel coordinates around the pixel.
Directions are degree numbers from 0 to 315.
in:
* screen (a BufferedImage)
* x (a Number)
* y (a Number)
out: a map of maps, for example,
{direction {:color some-color
:x x
:y y}
...}
where `direction`, `some-color`, `x`, and `y` are all numbers."
~~~
Not only will that be easier to read, but also I suspect that API doc
generator tools will eventually have optional support for treating
docstrings as md and rendering them as html. (Hm, come to think of it, I
opened an issue for codox a little while back regarding this
<https://github.com/weavejester/codox/issues/14>.)
---John
--
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
