Many public vars have no :added metadata

Question

There is a deftest named public-vars-with-docstrings-have-added in file test/clojure/test_clojure/metadata.clj explicitly for the purpose of failing if any public vars do not have :added metadata.

That test considers them public if they are not private, and in any of the namespaces defined earlier in the vector public-namespaces

That public-namespaces vector hasn't been updated since 2010, so is missing several namespaces that have been added since then.

If there is any desire to add more namespaces to that list, several of them cause the test to fail. I will add an attachment containing a list all vars that are listed as missing :added metdata across all namespaces, but do not yet have any suggestions for which namespaces should be considered in that list, and which should be left out on purpose (except for deprecated namespaces like clojure.parallel).

Answer 1

Comment made by: jafingerhut

Attached file clj-2519-partial-v1.patch is a diff that I compiled with locally on my machine. I am not 100% certain it includes all namespaces that are part of Clojure 1.10, but it should be close if not complete.

Attached file clj-2519-public-vars-without-added-meta.txt, which with the released source code for Clojure 1.10.1 plus that patch above shows the list of public vars in those new namespaces that fail the test, because they do not have :added metadata.

Answer 2

Comment made by: admin

Let's narrow to these: https://clojure.atlassian.net/secure/attachment/18679/clj-2519-vars-to-update.txt

Answer 3

_Comment made by: jafingerhut_

Thanks for the list!  Working on tracking down correct :added versions for all of those symbols.

I believe that for anything that was present in Clojure 1.0, we want:

{:added "1.0"}

and there is no reason to determine when earlier than that it may have been added?

Example symbol: clojure.main/repl

Aside: I am using the REPL on many different versions of Clojure to determine when the symbols were present vs. not, which seems faster than looking through git logs.  I guess I shouldn't be, but a bit surprised that clj/clojure can be used to start up a Clojure 1.0.0 REPL just fine.

Answer 4

Comment made by: admin

Correct on 1.0 - anything older should be 1.0.

clj is just running clojure.main in the clojure version you tell it (and the repl hasn't really changed, other than additively), so I would be surprised if it didn't work! :)

Answer 5

Comment made by: jafingerhut

Patch clj-2519-v2.patch adds :added metadata for everything in Alex Miller's suggested list in attachment clj-2519-vars-to-update.txt

I verified the version numbers for all such metadata by starting a REPL with that released version of Clojure, verifying I could require the namespace and resolve the var there, and that one or both of those operations failed with the previous released version of Clojure. Hopefully I didn't mess up any of those. I can try writing a bash script or something that demonstrates the results I saw if that would help review it.

Answer 6

Comment made by: jafingerhut

OK, I went a bit intense on writing a program to check whether my :added annotations had the correct version, and wrote some code that checked all public vars, or at least the ones that the public-vars-with-docstrings-have-added deftest does, to see in which released versions of Clojure they successfully resolve, and which they do not (or their namespace didn't even exist in that version of Clojure yet).

All of the :added metadata in patch clj-2519-v2.patch is confirmed to have the correct version number using that program.

I found 24 public vars that may not have the correct :added version number, but they are all cases where the :added version is "1.3" or earlier, and the corrected one would also be "1.3" or earlier. Is there any interest in correcting any of those?

Examples: All of these vars have :added "1.0", but that was probably copied from the implementation of the similarly named function without the "-int" suffix in the name. The "-int" suffix named ones were actually added in Clojure 1.3:

unchecked-add-int
unchecked-dec-int
unchecked-divide-int
unchecked-inc-int
unchecked-multiply-int
unchecked-negate-int
unchecked-remainder-int
unchecked-subtract-int

For inc and inc', when inc' was first added way back before Clojure 1.2, inc had :added "1.0" and inc' had added "1.2", which was correct. Some time before 1.3 was released, the names were swapped on those two function definitions, but the :added values stayed with the implementation body of the function, and ever since then we have inc with :added "1.2" and inc' with :added "1.0". Similarly for other functions with the single quote at the end of their names, I believe.

Answer 7

Comment made by: admin

don't care

Answer 8

Reference: https://clojure.atlassian.net/browse/CLJ-2519 (reported by jafingerhut)