Clojure

chunk-* functions not documented

Details

  • Type: Enhancement Enhancement
  • Status: Open Open
  • Priority: Minor Minor
  • Resolution: Unresolved
  • Affects Version/s: Release 1.5
  • Fix Version/s: None
  • Component/s: None
  • Labels:
  • Patch:
    Code

Description

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?

Activity

Hide
Ben Moss added a comment -

Did my best to explain these functions as I understand them.

Show
Ben Moss added a comment - Did my best to explain these functions as I understand them.
Hide
Andy Fingerhut added a comment -

Ben, the correct order for adding doc strings to a defn is like this:

(defn ^:static ^clojure.lang.ChunkBuffer chunk-buffer
  "Returns a fixed length buffer of the given capacity."
  ^clojure.lang.ChunkBuffer [capacity]
  (clojure.lang.ChunkBuffer. capacity))

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?

Show
Andy Fingerhut added a comment - Ben, the correct order for adding doc strings to a defn is like this:
(defn ^:static ^clojure.lang.ChunkBuffer chunk-buffer
  "Returns a fixed length buffer of the given capacity."
  ^clojure.lang.ChunkBuffer [capacity]
  (clojure.lang.ChunkBuffer. capacity))
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?
Hide
Alex Miller added a comment -

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.

Show
Alex Miller added a comment - 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.
Hide
Ben Moss added a comment -

Sorry for the rookie mistake, Andy. As for whether these are intended to be documented at all, I don't really know.

Show
Ben Moss added a comment - Sorry for the rookie mistake, Andy. As for whether these are intended to be documented at all, I don't really know.
Hide
Andy Fingerhut added a comment -

Ben, that is a rookie and experienced-Clojure-developer mistake, as I have learned from running Eastwood on many Clojure projects written by experienced Clojure developers. There were (and still are I think) some occurrences of it in Clojure itself.

Show
Andy Fingerhut added a comment - Ben, that is a rookie and experienced-Clojure-developer mistake, as I have learned from running Eastwood on many Clojure projects written by experienced Clojure developers. There were (and still are I think) some occurrences of it in Clojure itself.
Hide
Andy Fingerhut added a comment -

Ben, your patch document_chunk_fns_v2.patch dated Aug 6 2014 applies cleanly to latest master, but causes Clojure's tests to fail. This is because there is a test that ensures that every function in clojure.core with a doc string also has :added metadata. This can be corrected if you create :added metadata for the functions where you add doc strings. Search for :added in core.clj for examples. See "How to run all Clojure tests" on this wiki page: http://dev.clojure.org/display/community/Developing+Patches

Show
Andy Fingerhut added a comment - Ben, your patch document_chunk_fns_v2.patch dated Aug 6 2014 applies cleanly to latest master, but causes Clojure's tests to fail. This is because there is a test that ensures that every function in clojure.core with a doc string also has :added metadata. This can be corrected if you create :added metadata for the functions where you add doc strings. Search for :added in core.clj for examples. See "How to run all Clojure tests" on this wiki page: http://dev.clojure.org/display/community/Developing+Patches

People

Vote (0)
Watch (0)

Dates

  • Created:
    Updated: