On Saturday, April 25, 2015 at 1:47:27 AM UTC-4, Mike Rodriguez wrote:
>
> I agree about wanting to use the explicit argument name surrounded by
> markdown quotes in docs. I've definitely started adopting this practice and
> wish there were conventions around this sort of thing. Without it, doc
> strings can easily get ambiguous and confusing in how they relate the the
> actual arguments of the function (in function docs that is).
>
> I also try to make it a point to mention each argument of he function in
> the doc string...
I don't know what exactly is meant by "markdown quotes", but here's a style
I saw in the docstrings for a game dungeon generator written in Clojure:
"Erodes one or more chasms, rivers of water or lava, canyons, or etc. or
builds one or more walls across a dungeon, depending on the passed in
template. Affected squares are subjected to erode-square. If num-chasms
is
higher than 1, num-chasms wrap-around chasms will be created that each
randomly runs in one of 8 directions: north-south, east-west, NE-SW,
NW-SE,
and the four directions that have a 1:2 or 2:1 gradient. If num-chasms
is 1,
up to three chasms will actually be created. There will be a master chasm
that is a wrap-around chasm as per the above, with equal probabilities of
these five outcomes:
1. There is only the master chasm created, and it lacks an island.
2. The master chasm has an island of unaffected dungeon in a wide spot
at a
random place; equivalently, it forks and rejoins in one area.
3. There is a secondary chasm that runs from a random point along the
master
chasm, wraps at a random dungeon border, and ends at the master chasm
at a
usually-different random point. This chasm is narrower than the master
chasm.
4. As in 3, but the master chasm also has an island as in 2, generally
away
from either of the endpoints of the secondary chasm.
5. As in 3, plus there's a tertiary chasm, narrower still, that joins a
random point of the secondary chasm to a random point of the primary
chasm, without wrapping. The latter point is generally not near
either of
the secondary chasm's endpoints. A triangular island is generally the
result, bounded by sections of all three chasms, one on each side.
If only the master chasm is created, or if num-chasms > 1, then if any
master
chasm runs north-south, ENE-WSW, or ESE-WNW, the dungeon gains an
:ewblocked
true mapping, and if any master chasm runs in any other direction the
dungeon
gains an :nsblocked true mapping. If a secondary chasm is created both
mappings are created. Exception: neither mapping is created if the
template
is a wall or a floor square. These keys interact with build/create-rpm
when
one wants chasms to inhibit wrapping as much as possible and then only
artificially inhibit rooms/passages from wrapping to the extent that
chasms
inhibited it.
Arguments:
d - dungeon to modify
num-chasms - see above. Optional. Defaults to 1.
template - chasm squares are changed into this
width - master chasm is this wide; secondary is 1/4 to 3/4 this wide and
tertiary is 1/4 to 3/4 as wide as secondary, all with a minimum
of 2.
variance - width of master chasm can vary by +/- this much. Variances of
secondary and tertiary chasms are scaled down with their
widths.
v2 - effectively randomly perturbs width. If num-chasms > 1, each has
its own
randomly adjusted width. If num-chasms == 1, the master chasm does,
and
its width in turn influences any secondary and tertiary chasms'
widths
as per the above.
no-secondary-features? - if true, and num-chasms is 1, only the master
chasm
is created -- no islands, secondary chasms,
etc.;
ignored if num-chasms > 1 (treated as true).
Optional. Defaults to false."
That project had hundreds of functions like these spread across a moderate
number of namespaces, and seemed to embody a fair degree of simulation
detail -- inspired by Dwarf Fortress, perhaps? And super-documented. I
wouldn't be surprised if there were more LOC in docstrings than in actual
executable clojure, based on browsing the repository. The author clearly
made sure that if he erred, it was on the side of over-documenting rather
than under-documenting everything.
The relevant thing here is that there's a separate section of the function
docs just listing arguments, by name, with their effects. No room for
ambiguity there. Nearly all of them start with "d - dungeon to modify", as
well, so clearly that API was designed with the thread-first macro in mind
for performing sequences of transformations.
--
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.
