This is my last reply for this thread as the support for "improved" doc strings for symbol and keyword has been kind of underwhelming - which is fine - time to move on. (besides, now I personally know more than enough about the implementation of those functions to use them conformantly ;-) )
> Surely undocumented behavior is undefined behavior by definition? True - but that kind of assumes that there is documented behavior… the one-liner for (symbol ns name) doesn't say anything about input parameter value types, and leaves the valid characters set upto the user knowing where to find it on the "http://clojure.org/reader"; page. Note that I had to find the valid types for [name] and [ns name] by looking thru the clojure.core clj&java code. > ...unless explicitly documented to the > contrary (e.g., when given invalid input, this function shall throw an > exception). It took me about 3 minutes to scan thru the API list and testing at the repl to find alias, bases and bound? - all throwing exceptions while it is not mentioned in their docs. I'm sure you could have found many more in the same time before you wrote your reply - not sure what that tells you (?). Also not sure what the big issue is to help the (novice) users out by being explicit in the doc-string about the contract and behaviour of a function. As far as I can tell, you have functions that validate and barf, validate and return some well-known value like nil for invalid input, and you have the garbage-in, garbage-out type. Unless you can guarantee that the first two types are always clearly identified in their docs, you can leave the last one open… however, why not mention it also explicitly? Especially for symbol, which is a pretty key entity for the clojure language. We have a one-liner, low on content for symbol/keyword and a page-long doc for deftype/defprotocol. So one last time… instead of having the current docs: clojure.core/symbol ([name] [ns name]) Returns a Symbol with the given namespace and name. clojure.core/keyword ([name] [ns name]) Returns a Keyword with the given namespace and name. Do not use : in the keyword strings, it will be added automatically. My suggested docs are: clojure.core/symbol ([name] [ns name]) Returns a Symbol with the given namespace and name. (symbol name): name can be string or symbol. (symbol ns name): ns and name must both be string. A symbol string, begins with a non-numeric character and can contain alphanumeric characters and *, +, !, -, _, and ?. (see "http://clojure.org/reader"; for details). Note that function does not validate input strings for ns and name, and may return improper symbols with undefined behavior for non-conformant ns and name. clojure.core/keyword ([name] [ns name]) Returns a Keyword with the given namespace and name. Do not use : in the keyword strings, it will be added automatically. (keyword name): name can be string, symbol or keyword. (keyword ns name): ns and name must both be string. A keyword string, like a symbol, begins with a non-numeric character and can contain alphanumeric characters and *, +, !, -, _, and ?. (see "http://clojure.org/reader"; for details). Note that function does not validate input strings for ns and name, and may return improper keywords with undefined behavior for non-conformant ns and name. Take it or leave it. Regards, FrankS. </email-thread> On Mar 12, 2012, at 4:56 PM, Sean Corfield wrote: > On Mon, Mar 12, 2012 at 10:39 AM, Armando Blancas <abm221...@gmail.com> wrote: >>> If invalid input will not throw an error >>> immediately, then it DOES need to be documented that invalid input >>> will result in undefined output. >>> >>> ~Justin >> >> Documented by whom? By you and FrankS? Maybe the push back is for lotta >> suggestin' but little doin'. > > Surely undocumented behavior is undefined behavior by definition? > That's certainly the approach taken by many programming language > standards. In which case, giving any function invalid input is > immediately in undefined behavior territory and the output is > "guaranteed" to be undefined - unless explicitly documented to the > contrary (e.g., when given invalid input, this function shall throw an > exception). > -- > Sean A Corfield -- (904) 302-SEAN > An Architect's View -- http://corfield.org/ > World Singles, LLC. -- http://worldsingles.com/ > > "Perfection is the enemy of the good." > -- Gustave Flaubert, French realist novelist (1821-1880) > > -- > 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 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
