Re: Meaning of part of the doc string for `ns-resolve`
I have found long docs like that to be useful in some major top-level function if it has a large sort of input and configuration parameters to pass in. Markdown I believe means with back ticks around the symbol to make it stand out as an actual art name vs some other word in the sentence. I have seen this be a popular doc style in lisps that I've looked at. When case insensitive I've seen all caps used, which would not work in Clojures case. I've like the back tick markdown style since it doesn't get as easily confused with something like quote. I've also tended to use markdown ticks around code expressions of they were used in the doc string. I'm not sure I've seen a lot of that in the wild though. Doing that on every(most) function I'd be worried would be a maintenance issue. I've wrote doc string style where the arguments are enumerated in an obvious argument name -> description way. It definitely makes it unambiguous. I still tend to reserve that for "larger", more complex functions. While in simpler functions just ensuring all args referenced directly and markdown ticked and are described in a natural type of sentence/paragraph. The idea of consistently naming arguments/types of arguments a certain way is obviously nice too -- 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.
Re: Meaning of part of the doc string for `ns-resolve`
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 ne
Re: Meaning of part of the doc string for `ns-resolve`
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... -- 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.
Re: Meaning of part of the doc string for `ns-resolve`
Nicola Mometto wrote: It's talking about fully qualified symbols that map to an actual var. E.g user=> (ns-resolve *ns* 'clojure.string/join) #'clojure.string/join Ah. Thank you. Ambrose Bonnaire-Sergeant wrote: > Could you clarify why you expect that? > > Thanks, > Ambrose > Because "the namespace" is ambiguous in the sentence. It could mean either "the namespace that qualifies the symbol" or "the namespace that is the first argument to `ns-resolve`". Having been confused by this in the past, I've started trying to be explicit when mentioning variables, always using the explicit variable name, and surrounding the name with `markdown quotes`. -- 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.
Re: Meaning of part of the doc string for `ns-resolve`
This fails: (ns-resolve 'sumtin 'clecs.world/remove-entity) Exception No namespace: sumtin found clojure.core/the-ns (core.clj:3830) But this succeeds: (ns-resolve 'seesaw.core 'clecs.world/remove-entity) #'clecs.world/remove-entity It seems when the 2nd argument is fully qualified, first argument is not important but it still needs to be a valid namespace. On Fri, Apr 24, 2015 at 1:43 AM, Brian Marick wrote: > The last sentence of the `ns-resolve` documentation reads: > > Note that > if the symbol is fully qualified, the var/Class to which it resolves > need not be present in the namespace. > > What does that mean? I would expect something like the following to > produce a non-nil value: > > user=> (ns-resolve 'clojure.core 'fofofof) > user=> (ns-resolve 'clojure.core 'clojure.core/fofofof) > user=> (ns-resolve *ns* 'clojure.core/fofofof) > > > ... to produce a non-nil value, but they're all nil. > > (Note: in the 1.6 API, it looks to me like the only other uses of "fully > qualified" refer to classes.) > > -- > 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. > -- Kind Regards, Atamert Ölçgen ◻◼◻ ◻◻◼ ◼◼◼ www.muhuk.com www.olcgen.com -- 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.
Re: Meaning of part of the doc string for `ns-resolve`
It's talking about fully qualified symbols that map to an actual var. E.g user=> (ns-resolve *ns* 'clojure.string/join) #'clojure.string/join Brian Marick writes: > The last sentence of the `ns-resolve` documentation reads: > >Note that >if the symbol is fully qualified, the var/Class to which it resolves >need not be present in the namespace. > > What does that mean? I would expect something like the following to > produce a non-nil value: > > user=> (ns-resolve 'clojure.core 'fofofof) > user=> (ns-resolve 'clojure.core 'clojure.core/fofofof) > user=> (ns-resolve *ns* 'clojure.core/fofofof) > > > ... to produce a non-nil value, but they're all nil. > > (Note: in the 1.6 API, it looks to me like the only other uses of "fully > qualified" refer to classes.) -- -- 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.
Re: Meaning of part of the doc string for `ns-resolve`
Could you clarify why you expect that? Thanks, Ambrose On Thu, Apr 23, 2015 at 6:43 PM, Brian Marick wrote: > The last sentence of the `ns-resolve` documentation reads: > > Note that > if the symbol is fully qualified, the var/Class to which it resolves > need not be present in the namespace. > > What does that mean? I would expect something like the following to > produce a non-nil value: > > user=> (ns-resolve 'clojure.core 'fofofof) > user=> (ns-resolve 'clojure.core 'clojure.core/fofofof) > user=> (ns-resolve *ns* 'clojure.core/fofofof) > > > ... to produce a non-nil value, but they're all nil. > > (Note: in the 1.6 API, it looks to me like the only other uses of "fully > qualified" refer to classes.) > > -- > 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. > -- 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.
Meaning of part of the doc string for `ns-resolve`
The last sentence of the `ns-resolve` documentation reads: Note that if the symbol is fully qualified, the var/Class to which it resolves need not be present in the namespace. What does that mean? I would expect something like the following to produce a non-nil value: user=> (ns-resolve 'clojure.core 'fofofof) user=> (ns-resolve 'clojure.core 'clojure.core/fofofof) user=> (ns-resolve *ns* 'clojure.core/fofofof) ... to produce a non-nil value, but they're all nil. (Note: in the 1.6 API, it looks to me like the only other uses of "fully qualified" refer to classes.) -- 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.
