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.