[CLJ-1002] chunk-* functions not documented Created: 27/May/12 Updated: 01/Jul/14
|Affects Version/s:||Release 1.5|
None of the chunk related functions defined in core.clj have documentation. While their implementations are straightforward, it means the functions do not show up in http://clojure.org/api. Are these not considered part of the API? If so, should they be private? Otherwise, I think they should have public documentation.
For searchability, the function are:
chunk-append, chunk, chunk-first, chunk-rest, chunk-next, chunk-cons, chunked-seq?
|Comment by Ben Moss [ 01/Jun/14 3:38 PM ]|
Did my best to explain these functions as I understand them.
|Comment by Andy Fingerhut [ 01/Jul/14 10:02 AM ]|
Ben, the correct order for adding doc strings to a defn is like this:
with the doc string after the symbol that names the function, but before the argument vector.
The Clojure compiler gives no errors or warnings if you do it in the order, that is true. However, it also does not attach the provided string as documentation metadata, and thus (doc fn-name) will not print the doc string.
Could you update the patch to put the proposed doc strings in the correct place?
|Comment by Alex Miller [ 01/Jul/14 10:13 AM ]|
FYI, there are several functions in clojure.core that are not private (because they are useful to implementors outside core) but also not documented so they don't show up in public api (because they are not considered part of the api). It's possible that these functions fall in that category and are intentionally undocumented, however I am unsure.