<< Back to previous view

[TCHECK-14] re-organize README and doc/ Created: 29/Mar/14  Updated: 29/Mar/14

Status: Open
Project: test.check
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Reid Draper Assignee: Reid Draper
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

I'd like to re-organize the README, and focus on making it easier for users to find the information they need. The README is currently pretty long, and could be information overload. My current thinking is that the new README should be short, and focus on providing links to people based on their experience with test.check. I think something like the following three headings would be useful:

1. First time user. Show me what this is all about.

  • Focus on 'seeing something cool' within five minutes. Maybe include some example tests in examples/. This way new users can simply clone the repository and run a test in under two minutes.

2. Still getting started, show me some tutorials and examples.

  • This will probably build on the existing doc/intro.md file, which currently describes how to write generators.

3. Existing user, show me API documentation, release notes, advanced techniques.

  • API documentation
  • Release-notes, make it clear these are up-to-date, and have clear instructions when there are breaking changes
  • Advanced techniques/tutorials





[TCHECK-9] Properly document how :max-size works Created: 04/Mar/14  Updated: 14/Apr/14

Status: Open
Project: test.check
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Jean Niklas L'orange Assignee: Reid Draper
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

I have had several issues where I thought increasing quick-check's num-tests argument would increase the time taken linearly, but surprisingly it grew quadratically. This is related to the auto-increasing of the size to call-gen, which I believe it isn't documented well enough. It also seems like other people have had trouble with this functionality, see the reply to announcement of clojure.test.check.

Preferably, it should be mentioned in the docstring and the tutorial that the size of the structures generated grows linearly with the amount of tests you have, up to 200. As a result, doubling the amount of tests does not necessarily double the amount of time taken to run the tests.

In some of my tests, this behaviour increases the running time exponentially, and I actually used quite some time figuring out why. The documentation on recursive generators decreases the size of the binary tree in half, but it is not explained why it is split in half. While obvious in hindsight, explicitly explaining that recursive structures should have an amount of nodes proportional to the input size argument and how it is done, would be beneficial.



 Comments   
Comment by Reid Draper [ 04/Mar/14 8:50 PM ]

+1. This is not well-documented now. Further, I'm still not 100% sure that halving inside of a recursive generator is the right thing to do. For some structures, log2 may be more appropriate. In the mailing list post you mention, gen/any is clearly not bounded enough at roughly size=90, consider it's using more than 1GB of heap.

Comment by Reid Draper [ 14/Apr/14 8:58 PM ]

I've made things a little better in 57df9b9b8f2fe61a798fbf683046e8d1aa128228.





[NREPL-61] Typo in README Created: 22/Aug/14  Updated: 22/Aug/14  Resolved: 22/Aug/14

Status: Closed
Project: tools.nrepl
Component/s: None
Affects Version/s: 0.2.4
Fix Version/s: 0.2.5

Type: Defect Priority: Trivial
Reporter: Bozhidar Batsov Assignee: Bozhidar Batsov
Resolution: Completed Votes: 0
Labels: documentation

Attachments: Text File 0001-Fix-a-typo-and-remove-some-trailing-whitespace.patch    
Patch: Code

 Description   

Just a small typo fix.



 Comments   
Comment by Chas Emerick [ 22/Aug/14 8:01 AM ]

Applied as 222c456. Thanks!





[NREPL-43] Document the availability/usage of *e, *1, *2, ... in nREPL Created: 04/Jul/13  Updated: 24/Aug/13

Status: Open
Project: tools.nrepl
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Jakub Holy Assignee: Chas Emerick
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

I have only by chance discovered that nREPL binds the lat error/outputs to the vars *e, *1 etc. This should be documented clearly somewhere, possibly in https://github.com/clojure/tools.nrepl/blob/master/README.md

When I have forgotten the names of the vars while remembering that something like them exists, I tried to google them out but failed. So better documentation would help.

Thank you!



 Comments   
Comment by Chas Emerick [ 04/Jul/13 7:07 AM ]

The role of those vars is actually the same across all Clojure REPLs. In this department, nREPL is simply following Clojure's lead.

That said, yes, there is room to specify fully what nREPL's behaviour is, beyond the implied equivalence (at a minimum) to Clojure's included console REPL.

Comment by Jakub Holy [ 22/Jul/13 7:37 AM ]

Thank you for the clarification!

> The role of those vars is actually the same across all Clojure REPLs.

Do you know if this behavior of all Clojure REPLs is documented anywhere? And yes, it would be nice if the nREPL documentation linked to this doc and/or it printed a short summary and/or link when starting (in addition to the currently provided info about (source) etc.)

Thanks!

Comment by Chas Emerick [ 22/Jul/13 7:52 AM ]

REPL-bound vars are documented in a variety of places, though nowhere "official" AFAIK. We talked about it in Chapter 10 of Clojure Programming FWIW (I'm certain other books and online resources cover these vars as well, but the CP citation is the only one I have close at hand.)

FYI, the "currently-provided info" you mention is emitted by Leiningen/Reply, not nREPL.

Comment by Jakub Holy [ 24/Aug/13 4:50 AM ]

Thanks a lot, Chas, that was helpful. I have submitted a patch to Leiningen to include the info it its REPL' welcome message: https://github.com/technomancy/leiningen/pull/1310

Comment by Jakub Holy [ 24/Aug/13 5:38 AM ]

I have published a blog post about this, Clojure REPL stores the latest results in *1, *2, *3, exception in *e, to make it more googlable (is that even a word? ).

The top hit for "Clojure REPL" seems to be http://clojure.org/repl_and_main, so it perhaps should be documented there or it should link to a more detailed documentation. Not sure how to make that happen I have also checked http://clojure-doc.org/ but there doesn't seem to be a suitable place to add this info either. Perhaps it should be mentioned in the docstring of clojure.main/repl and the Clojure page should link to it?

Comment by Jakub Holy [ 24/Aug/13 5:52 AM ]

I have created an issue under Clojure itself, #CLJ-1247, so this can likely be closed.





[MTOWER-1] README should be updated to conform to contrib standard Created: 16/Sep/12  Updated: 17/Sep/12  Resolved: 17/Sep/12

Status: Resolved
Project: math.numeric-tower
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Trivial
Reporter: Christian Romney Assignee: Mark Engelberg
Resolution: Completed Votes: 0
Labels: documentation, patch

Attachments: Text File 0001-Improved-README-to-follow-standard-for-contrib.patch     Text File 0001-Improved-README-to-follow-standard-for-contrib.patch    
Patch: Code

 Description   

As per Sean Corfield's suggestion here: https://groups.google.com/forum/?fromgroups=#!searchin/clojure-dev/math/clojure-dev/p5oz42gR_sk/cesMHO9cDWEJ
the math.numeric-tower README.md should be updated to be more useful, especially to newbies.



 Comments   
Comment by Christian Romney [ 16/Sep/12 10:50 PM ]

Please ignore previous patch (doesn't format code examples correctly). This one looks better on Github. You can see it here: https://github.com/xmlblog/math.numeric-tower

Comment by Sean Corfield [ 17/Sep/12 11:33 AM ]

Patch applied.





[MCOMB-1] math.combinatorics README should be updated to conform to contrib standard Created: 17/Sep/12  Updated: 17/Sep/12  Resolved: 17/Sep/12

Status: Resolved
Project: math.combinatorics
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Trivial
Reporter: Christian Romney Assignee: Mark Engelberg
Resolution: Completed Votes: 0
Labels: documentation, patch

Attachments: Text File 0001-Updated-README-to-conform-to-new-contrib-standard.patch    
Patch: Code

 Description   

As per Sean Corfield's suggestion here: https://groups.google.com/forum/?fromgroups=#!searchin/clojure-dev/math/clojure-dev/p5oz42gR_sk/cesMHO9cDWEJ
the math.combinatorics README.md should be updated to be more useful, especially to newbies.



 Comments   
Comment by Sean Corfield [ 17/Sep/12 11:35 AM ]

Patch applied.





[LOGIC-131] Docstrings for lvaro and nonlvaro need improvement. Created: 22/Apr/13  Updated: 28/Jul/13  Resolved: 07/May/13

Status: Closed
Project: core.logic
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Defect Priority: Minor
Reporter: Austin Haas Assignee: David Nolen
Resolution: Completed Votes: 0
Labels: documentation

Attachments: File LOGIC-131-fix.diff    
Patch: Code

 Description   

Assuming the following definitions:

1. A term is ground if it does not contain unassociated logic variables.
2. Otherwise, it is non-ground.

My suggestions:

lvaro: A non-relational goal that succeeds if the supplied logic variable is fresh.

nonlvaro: A non-relational goal that succeeds if the supplied logic variable is not fresh.

In the case nonlvaro, it's important to recognize that the implementation only tests whether the supplied lvar is not fresh, and "not fresh" != grounded; the result could be partially instantiated. For example, nonlvaro succeeds here when its argument is neither fresh nor grounded:

(run* [q]
  (fresh [x]
    (== q [x])
    (nonlvaro q)))
;; => ([_0])


 Comments   
Comment by Austin Haas [ 22/Apr/13 12:26 PM ]

I added those initial definitions when I thought "groundedness" was the operative word, so they aren't directly relevant.

Comment by David Nolen [ 22/Apr/13 12:29 PM ]

Thanks, I'll happily accept docstring patches.

Comment by Austin Haas [ 07/May/13 2:11 PM ]

This patch changes the docstrings for lvaro and nonlvaro to be more accurate. This is a fix for LOGIC-131.

Comment by David Nolen [ 07/May/13 10:29 PM ]

fixed http://github.com/clojure/core.logic/commit/cc30fcb4f5690e928fa7103e5091b9de8aba0013





[LOGIC-33] Added usage section to readme.md Created: 15/Mar/12  Updated: 28/Jul/13  Resolved: 17/Mar/13

Status: Closed
Project: core.logic
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Trivial
Reporter: Linus Ericsson Assignee: David Nolen
Resolution: Declined Votes: 0
Labels: documentation

Attachments: Text File usage-added.patch    
Patch: Code

 Description   

added a short usage section in readme.md

the latest working repo was 0.6.7 for me, so that's what in the patch. (i have signed CA)



 Comments   
Comment by David Nolen [ 17/Mar/13 7:11 PM ]

Basic usage has since been added to README.md





[DFRS-4] Better document how to extend with custom readers and writers Created: 05/May/14  Updated: 06/May/14  Resolved: 06/May/14

Status: Resolved
Project: data.fressian
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Major
Reporter: Alex Miller Assignee: Alex Miller
Resolution: Completed Votes: 0
Labels: docstring, documentation

Approval: Ok

 Description   

This was requested over email as it was not particularly clear how to integrate custom handlers with the existing handler maps when creating readers and writers.

In particular, it was confusing how to properly create the handler maps using the provided utilities.



 Comments   
Comment by Alex Miller [ 05/May/14 8:38 PM ]

Created wiki page with an example and more info:

https://github.com/clojure/data.fressian/wiki/Creating-custom-handlers

Comment by Alex Miller [ 06/May/14 11:36 AM ]

docstrings updated for create-reader and create-writer.





[DCSV-3] Some minor documentation typos Created: 14/Jun/12  Updated: 15/Jun/12  Resolved: 15/Jun/12

Status: Resolved
Project: data.csv
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Defect Priority: Trivial
Reporter: Trent Ogren Assignee: Jonas Enlund
Resolution: Completed Votes: 0
Labels: docs, documentation, typo

Attachments: Text File 0001-Documentation-typo-fixes.patch    
Patch: Code

 Description   

I found a couple minor typos: one in the README, one in a docstring. I've included a patch.






[CMEMOIZE-10] Odd deprecation warning in face of correct API usage? Created: 29/Nov/13  Updated: 03/Dec/13

Status: Open
Project: core.memoize
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Defect Priority: Minor
Reporter: Magnar Sveen Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: documentation, errormsgs
Environment:

[org.clojure/core.memoize "0.5.6"]



 Description   

Calling

(clojure.core.memoize/ttl get-optimized-assets {} :ttl/threshold ms)

Results in this

WARNING - Deprecated construction method for lu cache; prefered way is: (clojure.core.memoize/lu function <base> <:lu/threshold num>)

This breaks my expectation in two ways:

  • If I'm using `ttl` wrong, I would expect a deprecation warning for that. Now I'm a little stuck.
  • If I'm using `ttl` right, I wouldn't expect a deprecation warning.

Now I am just confused. Am I using a deprecated API? In that case, what is the right one to use? Looking at the source code, I see

Please use clojure.core.memoize/ttl instead.

Which is what I am using, as far as I can tell.

Maybe not a very important issue, but it has me confused and unsure.



 Comments   
Comment by Magnar Sveen [ 03/Dec/13 12:12 AM ]

Turns out I got bit by the JVMs global namespace. Once I included 0.5.6, the ring-middleware-format in our stack also started using that updated version - with the wrong API.

Is it only node.js that has this dependency thing figured out properly?

Sorry about the misleading issue. I'd close it, but I don't have the rights to do so.





[CMEMOIZE-2] Deprecate Unk Created: 13/Dec/11  Updated: 03/Jun/13  Resolved: 03/Jun/13

Status: Resolved
Project: core.memoize
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Minor
Reporter: Fogus Assignee: Fogus
Resolution: Completed Votes: 0
Labels: documentation, unk


 Description   

core.memoize was originally Unk , but its inclusion into contrib means the latter is redundant. The Unk repo should indicate the move and change to a place for docs and examples. Likewise, a formal announcement should be made.



 Comments   
Comment by Fogus [ 03/Jun/13 9:40 AM ]

Removed metadata and comment references.





[CLJS-511] The quick start guide should be written to use lein-cljsbuild Created: 29/May/13  Updated: 29/Jul/13  Resolved: 29/Jul/13

Status: Closed
Project: ClojureScript
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Daniel Kaplan Assignee: Unassigned
Resolution: Declined Votes: 0
Labels: docs, documentation


 Description   

The first line of the quick start guide ( https://github.com/clojure/clojurescript/wiki/Quick-Start ) says:

"NOTE: The following instructions are useful if for some reason you need to use the ClojureScript compiler directly. For a more integrated workflow, Leiningen with lein-cljsbuild is recommended."

This being the case, my first impression of the page is that this isn't really a quick start guide, but a way to do things in an obsolete way. It should be updated to show the right way to get started instead of outsourcing the guide to the lein-cljsbuild page ( https://github.com/emezeske/lein-cljsbuild ) or, perhaps the quick start guide link on https://github.com/clojure/clojurescript should directly link to the lein-cljsbuild page



 Comments   
Comment by David Nolen [ 29/Jul/13 11:19 PM ]

Documenting community tools is not something we're going to take on.





[CLJS-392] Documentation says CLJS can open connections to the REPL server from a "file://" source, and you can't Created: 09/Oct/12  Updated: 27/Jul/13  Resolved: 24/Oct/12

Status: Closed
Project: ClojureScript
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Defect Priority: Trivial
Reporter: Nahuel Greco Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: bug, docs, documentation
Environment:

ClojureScript 0.0-1450



 Description   

At https://github.com/clojure/clojurescript/wiki/The-REPL-and-Evaluation-Environments there is the following paragraph:

"This is a problem for the browser-connected REPL because FireFox and Chrome both view opening a file from the file system and connecting to localhost:9000 as different domains.
(...)
Fortunately, Google has also run into this problem and has created something called a CrossPageChannel. Without going into the details, this allows an iframe served from one domain (the REPL) to communicate with the parent page which was served from another domain (the application server)."

From what I tested, you CANT connect to the REPL server at "http://localhost:9000/repl" if you initially loaded the page using the "file://" protocol. But you can if you loaded it from the same hostname on another port using "http://". The documentation is wrong, and also it needs to be clarified on what you really can change from the initial domain, like the port, without broking the REPL connection (or link to a CrossPageChannel documentation page with the details on what same-origin policy checks it can overcome).



 Comments   
Comment by David Nolen [ 23/Oct/12 7:00 PM ]

Are you unable to edit the wiki?

Comment by Nahuel Greco [ 24/Oct/12 9:27 AM ]

I didn't know the wiki had public write permissions. Also I don't know the exact CrossPageChannel limitations.

Comment by David Nolen [ 24/Oct/12 10:37 AM ]

The limitation is that it won't work with file://. We now provide a simple webserver that will serve the files present in the directory where you started browser REPL. If you goto http://localhost:9000/ we will serve index.html if it is present.

Comment by Nahuel Greco [ 24/Oct/12 10:47 AM ]

So CrossPageChannel overcomes the "same origin policy" for different ports, but not for different protocols. Thanks for the clarification.

Comment by David Nolen [ 24/Oct/12 2:48 PM ]

No problem, closing this one.





[CLJS-186] ClojureScript wiki/The-REPL-and-Evaluation-Environments - small issues Created: 19/Apr/12  Updated: 30/May/12

Status: Open
Project: ClojureScript
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Defect Priority: Minor
Reporter: Mike Lamb Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: documentation, wiki


 Description   

I just worked through the "The REPL and Evaluation Environments" wiki page and had to make the following change to get the example to work.

— The-REPL-and-Evaluation-Environments.md.0 2012-04-19 17:40:23.000000000 -0400
+++ The-REPL-and-Evaluation-Environments.md 2012-04-19 17:40:48.000000000 -0400
@@ -57,6 +57,7 @@
<body>
<div id="content">
<script type="text/javascript" src="out/goog/base.js"></script>
+ <script type="text/javascript" src="out/goog/deps.js"></script>
<script type="text/javascript" src="foo.js"></script>
<script type="text/javascript">
goog.require('foo');

Something else I noticed was that I didn't get the "Starting server on port 9000" message.



 Comments   
Comment by Brian Taylor [ 30/May/12 4:26 PM ]

In my environment, the deps.js script tag is appended to the page automatically as a side-effect of loading base.js.

base.js (line 613 in my release)

// Allow projects to manage the deps files themselves.
  if (!goog.global.CLOSURE_NO_DEPS) {
    goog.importScript_(goog.basePath + 'deps.js');
  }




[CLJ-1479] Typo in filterv example Created: 27/Jul/14  Updated: 07/Oct/14  Resolved: 07/Oct/14

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.6
Fix Version/s: Release 1.7

Type: Enhancement Priority: Trivial
Reporter: Bozhidar Batsov Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: documentation, ft

Attachments: Text File 0001-Fix-a-typo.patch    
Patch: Code
Approval: Ok

 Description   

filter -> filterv in changes.md

Screened by: Alex Miller






[CLJ-1477] Fixed a typo Created: 27/Jul/14  Updated: 07/Oct/14  Resolved: 07/Oct/14

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.6
Fix Version/s: Release 1.7

Type: Enhancement Priority: Trivial
Reporter: Bozhidar Batsov Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: documentation, ft

Attachments: Text File 0001-Fix-a-typo.patch    
Patch: Code
Approval: Ok

 Description   

Just a simple typo fix - "directy" -> "directly".

Screened by: Alex Miller






[CLJ-1441] Provide docs on how to reference imports that conflict with default ns class imports Created: 07/Jun/14  Updated: 07/Jun/14

Status: Open
Project: Clojure
Component/s: None
Affects Version/s: Release 1.6
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Howard Lewis Ship Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

This is related to CLJ-1440; a name clash on class "Compiler" between clojure.lang and another package.

The documentation does not address how to handle this cleanly; specifically, refer would appear to allow a way to exclude clojure.lang.Compiler, but does not.



 Comments   
Comment by Alex Miller [ 07/Jun/14 7:56 PM ]

refer is all about symbols that refer to Var. refer's docstring seems pretty clear on that to me.

Your conflict is on symbols that refer to a Class, which is the domain of import and has no exclusion facilities. The set of default imports is defined in RT.DEFAULT_IMPORTS and includes clojure.lang.Compiler along with everything in java.lang.*.

You can always fully-qualify any class you want to use in your ns, so that is one workaround available. Another is what Nicola suggested in CLJ-1440 - post-modify the ns after load.

Either ns or import could theoretically document more explicitly the list of auto-imports and recommend a solution to this problem. I'm not sure whether this is worth doing or would be accepted given the infrequency of the use case and availability of workarounds.

I tweaked http://clojure.org/namespaces to mention this.





[CLJ-1382] Vector sort order should be specified sufficiently to embrace sort-by-juxt Created: 13/Mar/14  Updated: 15/Mar/14  Resolved: 15/Mar/14

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.5
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Phill Wolf Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: data-structures, documentation, idiom


 Description   

Vectors of equal length sort in a way that seems natural – by
comparing their 0th elements, then their 1st, etc., until something
is different:

user> (def vv '(["c" 9] ["a" 100] ["a" 33] ["b" 8]))
#'user/vv
user> (sort vv)
(["a" 33] ["a" 100] ["b" 8] ["c" 9])

This property enables a blisteringly wonderful idiom for sorting
records by multiple keys:

user> (def mm (->> vv (map (fn [[p q]] {:p p :q q}))))
#'user/mm
user> (sort-by (juxt :p :q) mm)
({:p "a", :q 33} {:p "a", :q 100} {:p "b", :q 8} {:p "c", :q 9})

The sort-by-juxt idiom was described on briancarper.net[1], where it
was refined for Clojure 1.1 by Malcolm Sparks. Andy Fingerhut has
also written about it, thoroughly.[2]

Such lore gives it the odor of respectability, but the sort-by-juxt
idiom takes liberties beyond the documented behavior ("contract") of
vectors. APersistentVector indulges the idiom, but the clojure.org
Data Structures page does not say how vectors should compare.

The vector specification should be bolstered with enough traits of
vectors' sorting behavior to make the sort-by-juxt idiom safe to use
wherever Clojure might be implemented.

[1] http://briancarper.net/blog/488/sort-a-clojure-map-by-two-or-more-keys

[2] https://github.com/jafingerhut/thalia/blob/master/doc/other-topics/comparators.md



 Comments   
Comment by Alex Miller [ 13/Mar/14 9:52 PM ]

I don't understand what this ticket is asking for.

Comment by Andy Fingerhut [ 13/Mar/14 10:32 PM ]

It sounds like he is asking that the doc of clojure.core/compare say that vectors of equal length are compared in lexicographic order.

Comment by Phill Wolf [ 15/Mar/14 1:07 PM ]

"(sort-by (juxt" relies on a feature of vectors that the Clojure documentation does not guarantee. But using juxt in this way is part of the cultural fabric and helps make concise programs that "read like a definition" of the problem, to quote Halloway in "Programming Clojure". Therefore, let's document the sort order of equal-length vectors. I looked for this information on the Data Structures page, which has a section on vectors.

Comment by Alex Miller [ 15/Mar/14 11:11 PM ]

I added a line to the Vectors section on the Data Structures (http://clojure.org/data_structures) page: "Vectors are compared first by length, then each element is compared in order."





[CLJ-1356] clojure.org/agents calls out deprecated funcs Created: 17/Feb/14  Updated: 17/Feb/14  Resolved: 17/Feb/14

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Trivial
Reporter: Ryan Macy Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: agents, documentation, website


 Description   

""If any exceptions are thrown by an action function, no nested dispatches will occur, and the exception will be cached in the Agent itself. When an Agent has errors cached, any subsequent interactions will immediately throw an exception, until the agent's errors are cleared. Agent errors can be examined with agent-errors and cleared with clear-agent-errors.""

While it is true and those functions will do what it describes, they are listed as deprecated in the docs. Should we update this paragraph to reflect usage of `agent-error` and `restart-agent` instead?



 Comments   
Comment by Ryan Macy [ 17/Feb/14 11:38 AM ]

I hope I put this in the right place!

Comment by Alex Miller [ 17/Feb/14 12:32 PM ]

Yep, thanks!

Comment by Alex Miller [ 17/Feb/14 12:40 PM ]

Fixed.





[CLJ-1321] Documentation improvement for clojure.walk, to note use of recursion that can easily blow the JVM stack Created: 09/Jan/14  Updated: 09/Jan/14

Status: Open
Project: Clojure
Component/s: None
Affects Version/s: Release 1.5
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Lee Spector Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: documentation
Environment:

JVM



 Description   

prewalk and postwalk are use recursion in ways that will blow the stack for sufficiently deep nested structures.

I suggest that this be noted in various clojure.walk documentation strings since this kind of recursion/limit seems to be rare in Clojure, and hence will be unexpected.

(It'd be even better to remove the recursion/limit via something like zippers and iteration, but this issue is just a suggestion for improvement of the documentation.)






[CLJ-1247] Document the availability/usage of *e, *1, *2, ... in REPL Created: 24/Aug/13  Updated: 29/Aug/13  Resolved: 24/Aug/13

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.5
Fix Version/s: None

Type: Enhancement Priority: Major
Reporter: Jakub Holy Assignee: Alex Miller
Resolution: Completed Votes: 0
Labels: documentation, repl


 Description   

For new users of Clojure, it is very hard to find out that evaluation results in any Clojure REPL are bound to *1 - *3 and the latest exception to *e. Since it is a pretty useful feature, it should be documented at a visible place. Where that place is, I am not sure.

One possibility would be to add it to the docstring of clojure.main/repl and make http://clojure.org/repl_and_main link to it (i.e. in the "Launching a REPL" section, we could add something like "Read the <link to=somewhere>docstring of clojure.main/repl</link> to learn about options and available vars. See also utility functions/macros in the clojure.repl namespace."

Note: This was originally reported under nREPL in NREPL-43.



 Comments   
Comment by Alex Miller [ 24/Aug/13 2:52 PM ]

I updated the http://clojure.org/repl_and_main page to include much of this info.

Comment by Jakub Holy [ 29/Aug/13 3:16 AM ]

Lovely, thanks!





[CLJ-1215] Mention where to position docstring when using pre/postconditions on the Special Forms page Created: 07/Jun/13  Updated: 03/Sep/13  Resolved: 03/Sep/13

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.5
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Jakub Holy Assignee: Unassigned
Resolution: Declined Votes: 0
Labels: documentation


 Description   

The description of pre- and post-conditions doesn't mention where docstring should be when using them. Placing it wrong will lead to the conditions to be ignored.

At http://clojure.org/Special%20Forms--(fn%20name?%20[params*%20]%20condition-map?%20exprs*), change

(fn name? [params* ] condition-map? exprs*)

to

(fn name? [params* ] condition-map? docstring? exprs*)

or at least mention it in the description or use it in the example.

Thank you!



 Comments   
Comment by Alex Miller [ 03/Sep/13 8:59 AM ]

The fn special form does not take a docstring so this modification is not valid. fn takes docstrings via meta.

The defn macro does take a docstring but it is placed prior to the attr-map, not after the condition map. The defn docstring does mention that the docstring will be added to the var metadata for the fn (not on the fn itself).





[CLJ-1190] Javadoc for public Java API Created: 03/Apr/13  Updated: 11/Jan/14  Resolved: 11/Jan/14

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: None
Fix Version/s: Release 1.6

Type: Enhancement Priority: Critical
Reporter: Stuart Halloway Assignee: Stuart Halloway
Resolution: Completed Votes: 0
Labels: documentation

Attachments: File clj-1190-2.diff     File clj-1190-3.diff     Text File clj-1190.patch    
Patch: Code
Approval: Ok

 Description   

Publish javadoc for http://dev.clojure.org/jira/browse/CLJ-1188.

  • Add javadoc for public API classes (Clojure and IFn)
  • Add ant build target to generate the javadoc
  • Publish javadoc to the clojure project github pages (will be done manually)

Patch: clj-1190-3.diff (javadoc updates and a new Ant target)

Screened by: Stuart Halloway

Updated by: Alex Miller (moved clojure.api.API to clojure.java.api.Clojure and tweaked one example per Rich's suggestion)



 Comments   
Comment by Andy Fingerhut [ 18/Aug/13 3:57 AM ]

It seems that when this ticket is completed, it may also complete CLJ-19, too.

Comment by Alex Miller [ 04/Oct/13 1:46 PM ]

Maven javadoc is something like this (configuration as in http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html):

<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9.1</version>
        <configuration>
          <show>public</show>
          <verbose>true</verbose>
          <sourceFileIncludes>
            <include>API.java</include>
          </sourceFileIncludes>
          <sourcepath>${basedir}/src/jvm/clojure/api</sourcepath>
        </configuration>
      </plugin>

What is desired for inclusion in the javadoc? Just the clojure.api package and API class? If so is it worth automating the publishing of this API or just documenting a process to put someplace static?

Comment by Alex Miller [ 21/Oct/13 10:14 PM ]

Javadoc can be told what to doc either by package or by java source file. The Maven plugin only supports the source file version if the files are in the same directory (as far as I can tell).

Ant was a little easier to get going:

<target name="javadoc" depends="build"
         description="Creates javadoc for Clojure API.">
    <javadoc destdir="javadoc">
      <classpath>
        <path location="${build}"/>
      </classpath>
      <fileset dir="src/jvm">
        <include name="clojure/api/API.java"/>
        <include name="clojure/lang/IFn.java"/>
      </fileset>
    </javadoc>
  </target>

However, there is no way to omit the nested IFn primitive interfaces in either case. That's just not a thing. Presumably it would be possible to customize the standard doclet to omit whatever you wanted although it makes me throw up in my mouth a little to even suggest that as a necessity.

Comment by Stuart Halloway [ 22/Oct/13 9:12 AM ]

Including nonpublic interfaces is worse than having no Javadoc at all, IMO. We plan to change this API almost never, so one possibility it to just generate from a copy of the IFn source file that omits the primitives.

API should have a class level document.

The goal here is to publish the official Javadoc on the web. Following the javadoc jar convention is a potential separate goal, but out of scope here.

Comment by Alex Miller [ 22/Oct/13 9:36 AM ]

When I next get a chance I'll take a look at what customizing the standard doclet would take. If it looks ugly I'll bail out.

Comment by Alex Miller [ 22/Oct/13 9:43 PM ]

Modifying the standard doclet (a mystery shrouded in a thicket of Oracle docs) to generate javadoc for 2 classes is ridiculous. As Stu suggested, I just hacked the inner interfaces out of IFn and generated the attached javadoc with the ant target prior in the comments. I think we could probably turn off a few more of the bits and improve the title,etc then manually publish this set of files in the github pages somewhere.

Comment by Alex Miller [ 23/Oct/13 8:48 PM ]

Added an Ant build target that strips the inner interfaces of IFn and generates the javadoc. Still need to add class javadoc for both API and IFn.

Comment by Alex Miller [ 23/Oct/13 10:49 PM ]

Added a new patch that adds javadoc for the clojure.lang package, the IFn and API classes. It also has an Ant task that generates the javadoc in target/javadoc which you can run with ant javadoc.

Comment by Alex Miller [ 21/Nov/13 3:32 PM ]

The API will live here (prelim version there now): http://clojure.github.io/clojure/javadoc/

Comment by Rich Hickey [ 22/Nov/13 10:37 AM ]

We should never show things like (lookup and simultaneously use var):

API.var("clojure.core", "deref").invoke(printLength);

because people will put that in a loop.

Also, API.var seems like a lot of CAPS. I understand that's proper Java conventions but maybe we need to pick another name?

Comment by Alex Miller [ 05/Dec/13 10:58 AM ]

At Stu's request, I made the updates from our prior conversation, namely:
1) Moved clojure.api.API to clojure.java.api.Clojure and updated all references.
2) Made the example change suggested by Rich to avoid creating and invoking the var in one step.

Comment by Alex Miller [ 07/Dec/13 4:22 PM ]

Andy, please let me know before modifying screened patches as they need to be re-screened.

Comment by Alex Miller [ 07/Dec/13 4:23 PM ]

In this case, it looks like you didn't leave the old one so I'm not even sure what's different?

Comment by Alex Miller [ 07/Dec/13 4:24 PM ]

Oh, I'm misreading the comment history, you just changed the patch field. Carry on.





[CLJ-1038] Docstring for deliver doesn't match behavior Created: 07/Aug/12  Updated: 01/Mar/13  Resolved: 24/Aug/12

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.3, Release 1.4
Fix Version/s: None

Type: Defect Priority: Minor
Reporter: Colin Jones Assignee: Colin Jones
Resolution: Completed Votes: 0
Labels: documentation

Attachments: Text File 0001-Update-docstring-for-deliver-s-actual-behavior.patch     Text File correct-deliver-docstring.patch    
Patch: Code
Approval: Ok

 Description   

The docstring for deliver doesn't match the actual behavior. It says an exception gets thrown on multiple delivers, but that's no longer the case, as of 1.3 (hat tip to clgv on irc).

user=> (doc deliver)
-------------------------
clojure.core/deliver
([promise val])
  Alpha - subject to change.
  Delivers the supplied value to the promise, releasing any pending
  derefs. A subsequent call to deliver on a promise will throw an exception.
nil
(let [p (promise)] 
  (deliver p "hi") 
  (deliver p "bye") 
  @p)
;=> "hi"

This patch updates the docstring to reflect actual behavior: "will throw an exception." -> "will have no effect."



 Comments   
Comment by Stuart Halloway [ 10/Aug/12 1:48 PM ]

Both patches are correct. Colin's patch documents the side effect, my variant also commits to the return values. Take your pick.

Comment by Rich Hickey [ 10/Aug/12 3:09 PM ]

Don't doc return

Comment by Stuart Sierra [ 24/Aug/12 7:41 AM ]

CLJ-1038 Update docstring for deliver's actual behavior (patch applied Aug 15, 2012)





[CLJ-1019] ns-resolve doc has a typo Created: 30/Jun/12  Updated: 18/Aug/12  Resolved: 18/Aug/12

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.5
Fix Version/s: Release 1.5

Type: Defect Priority: Trivial
Reporter: Gabriel Horner Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: documentation

Attachments: Text File clj-1019-ns-resolve-doc-string-misspelling-patch1.txt     Text File fix_ns-resolve.patch    
Patch: Code
Approval: Ok

 Description   

The doc string for ns-resolve has a typo: environement should be environment.



 Comments   
Comment by Andy Fingerhut [ 12/Jul/12 12:54 PM ]

clj-1019-ns-resolve-doc-string-misspelling-patch1.txt dated July 12, 2012 is identical to fix_ns-resolve.patch of June 30, 2012, except it is in git format. It includes Gabriel's name and email address for proper attribution.

Comment by Aaron Bedra [ 14/Aug/12 8:07 PM ]

Patch applies cleanly against 4004d267e124f12b65b0d7fb6522f32a75e3c4fb. Submitter is a confirmed CA signer.





[CLJ-999] Wrong link in gh-pages index (api-index.html) Created: 18/May/12  Updated: 26/Jul/13  Resolved: 20/May/13

Status: Resolved
Project: Clojure
Component/s: None
Affects Version/s: Release 1.3
Fix Version/s: None

Type: Defect Priority: Trivial
Reporter: Bogdan Popescu Assignee: Tom Faulhaber
Resolution: Completed Votes: 0
Labels: docs, documentation

Patch: Code

 Description   

The api-index.html includes wrong links for the following:

  • All entries for all listed as part of clojure.test.tap
  • All entries for all listed as part of clojure.test.junit
  • All entries for all listed as part of clojure.core.protocols

The links point to pages that do not exist. The problem is that the documentation for those entries is on a "parent" page, for example, the link clojure.core.protocols-api.html#clojure.core.protocols/internal-reduce should have been clojure.core-api.html#clojure.core.protocols/internal-reduce

Not a huge bug for me, but you might want to get it fixed.

And please give my huge thanks to whoever is in charge of the documentation, I'm the developer behind Dash, a Mac OS X documentation browser, and I was in the process of creating a documentation set for Clojure, and because you guys have an index, you made my work 1000 times easier.



 Comments   
Comment by Andy Fingerhut [ 11/Mar/13 3:01 PM ]

Is this fixed now? Tom Faulhaber has regenerated the docs after the recent Clojure 1.5 release, and I think updated other things besides, so it might be.

Comment by Tom Faulhaber [ 11/Mar/13 4:43 PM ]

Nope, not fixed.

This one either slipped by me or came in right when I was changing jobs so didn't stick in my brain.

I'll take a look now. Thanks for the report, Bogdan, and thanks for the bump, Andy to get it on my radar.

Comment by Gabriel Horner [ 10/May/13 4:00 PM ]

Tom, I'm happy to help if you need it. Could you document on a wiki page how autodoc is run here? I couldn't find such a page.

Comment by Tom Faulhaber [ 20/May/13 4:18 PM ]

This is fixed with gh-pages commit 919143e (autodoc doesn't follow the regular Clojure release path since it's a website built off the source checkins).

Comment by Tom Faulhaber [ 20/May/13 4:24 PM ]

Gabriel, Thanks for the offer. I fixed this one, but may take you up on it if more come up.

There is currently no wiki page about the autodoc process but it's an excellent suggestion. I'll put it on my list to write something up. In the meantime source on the autodoc program itself is at https://github.com/tomfaulhaber/autodoc and a description of how it works is at http://tomfaulhaber.github.io/autodoc. Two caveats: (1) autodoc is currently undergoing a bunch of work (thus this bug fix) in preparation for a new release and (2) the documentation doesn't talk much about how it's used for documenting Clojure itself.





[CLJ-998] doc string for replace-first mentions non-existent replace-all Created: 18/May/12  Updated: 01/Mar/13  Resolved: 18/May/12

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.3
Fix Version/s: None

Type: Defect Priority: Minor
Reporter: Steve Miner Assignee: Unassigned
Resolution: Duplicate Votes: 0
Labels: documentation

Attachments: Text File 0001-fix-doc-string-for-replace-first.patch    
Patch: Code

 Description   

The doc string for clojure.string/replace-first says see also replace-all, which does not exist. The actual function is simply 'replace'.



 Comments   
Comment by Andy Fingerhut [ 18/May/12 11:42 AM ]

CLJ-870 patch file CLJ-753-870-905-combined-fix3.patch dated Feb 28, 2012 fixes this issue, some other doc string issues, and fixes to the code.





[CLJ-973] doc for *data-readers* is wrong about the format for data_readers.clj Created: 14/Apr/12  Updated: 14/Apr/12  Resolved: 14/Apr/12

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.4
Fix Version/s: None

Type: Defect Priority: Minor
Reporter: Steve Miner Assignee: Stuart Halloway
Resolution: Completed Votes: 0
Labels: documentation

Attachments: Text File 0001-CLJ-973-doc-for-data-readers.patch    
Approval: Ok

 Description   

Sometime recently, the format for data_readers.clj changed to require a read-time literal map instead of pairs of symbols. The doc string for *data-readers* should be updated to reflect the change.



 Comments   
Comment by Steve Miner [ 14/Apr/12 9:59 AM ]

Fixed doc string for *data-readers*





[CLJ-965] clojure.org/patches should have link to JIRA workflow wiki page added, and most content removed Created: 04/Apr/12  Updated: 10/May/12  Resolved: 10/May/12

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Andy Fingerhut Assignee: Unassigned
Resolution: Completed Votes: 1
Labels: documentation

Patch: Code

 Description   

http://groups.google.com/group/clojure-dev/browse_frm/thread/12e90e460aec29cb

Relevant text supporting this suggestion copied below:

[1] http://dev.clojure.org/display/design/JIRA+workflow

Only a few have permission to edit this page:

[2] http://clojure.org/patches

I have carefully reviewed the content of those two side by side, section by section, and it seems to me that they are either identical, or [1] is more up to date.

I am not proposing getting rid of [2], but instead do this:

Keep the first section headed "Submitting patches to Clojure and Clojure Contrib" exactly as it is now.

Immediately under the heading "So You Have an Idea...", put a single link, perhaps with one sentence or phrase, that points at [1]. Delete all other text from there down on [2]. You will lose nothing worth saving, and you will save future confusion as what is now [2] gets more and more stale.



 Comments   
Comment by Andy Fingerhut [ 04/Apr/12 2:32 PM ]

I am probably abusing the "Patch" attribute of this ticket. I've set it to Code to indicate that it is ready for screening/action, not that it actually has a patch. I suppose if you take a very broad view of patch, one that includes the English text describing the suggested web page changes to clojure.org/patches in the description, then it does have a patch.

Comment by Andy Fingerhut [ 24/Apr/12 4:09 PM ]

Another link that would be nice to update: On http://clojure.org/contributing there is a link with text "preferred process for submitting" that links to http://clojure.org/patches. It should link to http://dev.clojure.org/display/design/JIRA+workflow instead.

Comment by Alex Miller [ 10/May/12 8:38 PM ]

I have boldly made the suggested changes to the patches page as it seems imminently reasonable to avoid duplicating the more maintained version of the content. I added the sentence:

"Great! For more info on the process of creating issues in JIRA, creating and filing patches, tracking, screening and vetting patches, please visit the JIRA workflow page on the dev wiki." with a big wide link target to the jira workflow page.

If the powers that be deem my changes to be unsuitable, the powers that be can revert to the prior version here:
http://clojure.org/page/diff/patches/270799794

Comment by Alex Miller [ 10/May/12 8:40 PM ]

I also changed the link on http://clojure.org/contributing per the other comment.

Comment by Andy Fingerhut [ 10/May/12 8:49 PM ]

Between the two of us, Alex, we have just enough permissions to make the change to clojure.org and close the ticket Thanks!





[CLJ-953] drop-while doc string wrong, nil instead of logical false Created: 15/Mar/12  Updated: 30/Mar/12  Resolved: 30/Mar/12

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.3
Fix Version/s: Release 1.4

Type: Enhancement Priority: Trivial
Reporter: Eric Schoonover Assignee: Alan Dipert
Resolution: Completed Votes: 0
Labels: documentation, patch,

Attachments: File take-while_doc_string_CLJ-953.diff    
Patch: Code
Approval: Ok

 Description   
"Returns a lazy sequence of the items in coll starting from the first
-  item for which (pred item) returns nil."
+  item for which (pred item) returns logical false."





[CLJ-936] Improve docs about argument destructuring at clojure.org Created: 21/Feb/12  Updated: 01/Mar/13  Resolved: 27/Nov/12

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: None
Fix Version/s: Release 1.5

Type: Enhancement Priority: Minor
Reporter: Jakub Holy Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: documentation, web

Approval: Accepted

 Description   

What:
Make the description of argument destructuring more visible at http://clojure.org/special_forms, namely:

  • add a heading such as "<h4>Binding Forms (Argument Destructuring)</h4>" to the section describing it
  • make all occurences of "binding-form" a link to that heading, especially under the let and fn headings
  • for (fn ..) add a new second paragraph like "Regarding binding forms, also known as argument destructuring, <a href=#thea-new-heading>read more in the binding forms section</a> under the let special form."

Why:
It was always surprisingly difficult for me to google out the explanation of destructuring in Clojure and only today have I discovered that it is described pretty well under the let special form. Thus it should be made more visible to the readers (and preferably also search engines). (Even though Google has returned the page as one of the first matches, I had problems seeing it there - partly due to usually mistyping destructuring e.g. as deconstruction).

Thanks a lot!

PS: I haven't found a better way to report this, such as a commenting capability on the page itself.



 Comments   
Comment by Andy Fingerhut [ 12/Mar/12 6:03 PM ]

Jakub, I don't think I have authorization to edit those web pages in the way you suggest. I did want to comment that the most recent version of the Clojure cheatsheet at http://clojure.org/cheatsheet now has a link called "examples" in the "Special Forms" section that links to the 'let' section of the special forms documentation page.





[CLJ-917] clojure.core/definterface is not included in the API docs Created: 23/Jan/12  Updated: 20/Oct/12  Resolved: 20/Oct/12

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: Release 1.3
Fix Version/s: Release 1.5

Type: Defect Priority: Minor
Reporter: Tassilo Horn Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: documentation

Attachments: Text File 0001-Add-docstring-and-added-metadata-to-definterface.patch     Text File CLJ-917-definterface.patch    
Patch: Code
Approval: Ok

 Description   

Is definterface meant to be a public API? If yes, then it needs a docstring.



 Comments   
Comment by Tassilo Horn [ 25/Jan/12 2:28 PM ]

This patch obsoletes the previous one. The only addition is the insertion of :added metadata which is needed to make the tests pass.

Comment by Tassilo Horn [ 08/Mar/12 3:53 AM ]

Updated patch.

Comment by Stuart Sierra [ 23/Mar/12 9:04 AM ]

Screened, pending question for Rich: "Is definterface meant to be a public API?"

Comment by Tassilo Horn [ 31/May/12 1:45 AM ]

Rebased patch on current master.

Comment by Stuart Sierra [ 24/Aug/12 1:12 PM ]

Screened again. Still applies as of commit 1c8eb16a14ce5daefef1df68d2f6b1f143003140

Comment by Stuart Halloway [ 19/Oct/12 10:32 AM ]

The CLJ-971 patch I just added is the same as the original with grammar corrections.

Comment by Tassilo Horn [ 20/Oct/12 5:48 AM ]

Patch including Stu's grammar/typo fixes.

Sorry, contributors like to show up in the commit history, so I couldn't resist stealing my patch back from you.





[CLJ-19] GC Issue 15: JavaDoc for interfaces Created: 17/Jun/09  Updated: 03/Sep/13

Status: Open
Project: Clojure
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Major
Reporter: Anonymous Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   
Reported by richhickey, Dec 17, 2008
Add JavaDoc to those interfaces supported for public use - IFn,
IPersistentCollection etc.


 Comments   
Comment by Assembla Importer [ 24/Aug/10 6:44 AM ]

Converted from http://www.assembla.com/spaces/clojure/tickets/19

Comment by Assembla Importer [ 24/Aug/10 6:44 AM ]

richhickey said: Updating tickets (#8, #19, #30, #31, #126, #17, #42, #47, #50, #61, #64, #69, #71, #77, #79, #84, #87, #89, #96, #99, #103, #107, #112, #113, #114, #115, #118, #119, #121, #122, #124)

Comment by Kevin Downey [ 17/Nov/12 8:05 PM ]

this seems like a great task for someone just starting out contributing to clojure.





[CCONTRACTS-6] Add/improve docs of contract, clojure.core.contracts, etc. Created: 30/Apr/14  Updated: 30/Apr/14

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: Jakub Holy Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

Even though contract is a key thing in the library, it lacks a docstring.
The docstring of the ns could also have a few words pointing to the main functions
and how to use them.

contract

For contract, st. like would be nice (excuse my poor understanding of the lib):

Define a named and documented contract.

constraints => signature-constraint*
signature-constraint => argument-vector constraint-vector
constraint-vector => functions and expressions [=> functions and expressions]

The functions are applied to the arguments, an expressions is executed as-is.
Constraint following `=>` are post-conditions and may use `%` to refer to the return value.

Ex.:

(contract doubler
  "ensures doubling (sometimes)"
  [x] [number? => integer?]
  [x y] [(every? number? [x y])
           =>
         integer? (= (* 2 (+ x y)) %)])))

See also: with-constraints, defconstrainedfn, and clojure.core.contracts.constraints

ns

The ns docstring could be improved f.ex. like this

The public contracts programming functions and macros for clojure.core.contracts.
Primary usage: defconstrainedfn or contract and with-constraints.
Use provide for functions you don't control.

Other

There are other undocumented or too lightly documented fns/macros that would benefit
from improvements, f.ex.

  • what does _ do?
  • provide would benefit from a (even brief) example
  • require-with-constraints - what is it, when to use?
  • in - an example would be nice
  • whitelist - the argument should be 'thing' not 'things' to be consistent with the docstring and the fact that it is a single map/set
  • an example of using implies, <=>, etc. would be nice - currently I don't really know when/why to use it (not mentioning how) [perhaps in the ns docstring, all this functions docstring having "... see the ns docstring")
  • why is defconstrainedfn in constraints.clj and not contracts.clj as the other main fns?
    Why does provide use "kontracts" instead of "c" as with-constraints does? (The mismatch of "constraint" and "contract" - fn is with-constraints but takes contracts - is in itself confusing but that is another story.)
  • defconstrainedrecord has no doc

I would be really happy if at least some of these improvements were applied. I believe it would help to spread contract programming more.

Thank you!






[CCONTRACTS-5] Fix links in and display of documentation Created: 30/Apr/14  Updated: 30/Apr/14

Status: Open
Project: core.contracts
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: Jakub Holy Assignee: Fogus
Resolution: Unresolved Votes: 0
Labels: documentation


 Description   

There is a number of problems with the way the documentation is made available and interlinked:

  • Currently most people likely arrive to https://github.com/clojure/core.contracts and read the README - but it does not point to the docs in ./docs/ => add link to it there
  • It is not clear how the docs are expected to be browsed; I suppose that the .org
    files should be exported to ./docs/wiki/*.markdown yet not all of them are. I also
    suppose that the exported markdown files should be available under https://github.com/clojure/core.contracts/wiki, i.e. pushed to git@github.com:clojure/core.contracts.wiki.git
  • Some of the problems:
  • the link "return to documentation" on e.g. "with-constraints" should point to /clojure/core.contracts/wiki, not /clojure/core.contracts/docs.html
  • if wiki is really exported, the main page should mention it is immutable
  • links on the home page had one more 'wiki' in them (fixed manually in the wiki - will be overriden by the next export)
  • some links are broken, f.ex. [defconstrainedfn](/clojure/core.contracts/wiki/defconstrainedfn) on f.ex. contract; [with-constraints](/clojure/core.contracts/with-constraints/) (missing /wiki/), [defcontract](/clojure/core.contracts/wiki/defcontract/)

It would certainly help the project if the documentation was easier to access and browse

Thank you






[CCACHE-13] Deprecate Clache Created: 13/Dec/11  Updated: 14/Aug/12  Resolved: 14/Aug/12

Status: Resolved
Project: core.cache
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Minor
Reporter: Fogus Assignee: Fogus
Resolution: Completed Votes: 0
Labels: clache, documentation


 Description   

core.cache was originally Clache , but its inclusion into contrib means the latter is redundant. The Clache repo should indicate the move and change to a place for docs and examples. Likewise, a formal announcement should be made.






[ASYNC-88] Add Sonatype repository info to README for unreleased library Created: 27/Aug/14  Updated: 02/Sep/14  Resolved: 02/Sep/14

Status: Closed
Project: core.async
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Defect Priority: Minor
Reporter: Bridget Hillyer Assignee: Unassigned
Resolution: Completed Votes: 0
Labels: documentation


 Description   

It could be confusing for those not very familiar with Leiningen, Maven, etc. that there is a separate way to obtain SNAPSHOT versions of libraries vs. Released versions of libraries.

I believe an easy fix would be to have the following information directly in the README of unreleased contrib libraries (of which core.async is one):

To use Clojure and contrib library SNAPSHOTS in your Leiningen project, add the following to your project.clj:

:repositories {"sonatype-oss-public" "https://oss.sonatype.org/content/groups/public/"}



 Comments   
Comment by Alex Miller [ 02/Sep/14 9:50 AM ]

Done.

Comment by Alex Miller [ 02/Sep/14 10:02 AM ]

Actually, I have un-done this for core.async as we don't ever release SNAPSHOT versions of core.async, so it's thus a bit confusing. The canonical place we point people for this repo setup info is:

http://dev.clojure.org/display/community/Maven+Settings+and+Repositories

Comment by Bridget Hillyer [ 02/Sep/14 10:11 AM ]

I realized that this does not affect core.async after I made this ticket. Maybe something was down that day so I couldn't get the canonical release? So, right, this is not valid for core.async. But it would be for other (contrib?) libraries that do get SNAPSHOTs released.

The setup info that you pointed out:
http://dev.clojure.org/display/community/Maven+Settings+and+Repositories
would probably be useful from a usability standpoint in the READMEs themselves, including core.async.





[ASYNC-38] keep</> instead of map</> Created: 18/Nov/13  Updated: 02/Sep/14  Resolved: 02/Sep/14

Status: Closed
Project: core.async
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Leon Grapenthin Assignee: Unassigned
Resolution: Declined Votes: 0
Labels: documentation, enhancement, errormsgs


 Description   

One problem with using map< is when the supplied function returns nil. In such case (using the latest implementation from core.async [org.clojure/core.async "0.1.256.0-1bf8cf-alpha"]) one can take nil from a channel created with map<. This is otherwise only possible with closed channels. Putting nil on a channel normally throws an IllegalArgumentException.

With the current implementation of map< it is not possible to determine whether the source-channel was closed or the supplied function returned nil.

Notice that putting onto a channel created with map> throws an IllegalArgumentException when the supplied function returns nil as if you would put nil onto a channel.

My proposal is to add keep</> (where nil values returned from the supplied function are ignored and nothing is put) to the core library or to implement map</> as keep</> since having a real map</> instead of keep</> hardly makes sense when nil is not permitted anyways.



 Comments   
Comment by Leon Grapenthin [ 24/Apr/14 3:44 AM ]

It is still an issue in "0.1.278.0-76b25b-alpha" that you can only use impl.protocols/closed? to consistently determine whether a channel created with map</> was closed - if nil is one of your predicates return values.

Of course, you could use a predicate that never returns nil. But what should be the benefit of map</> being able to magically pass nil while everything else isn't?

Comment by Alex Miller [ 02/Sep/14 9:43 AM ]

All of the transformation functions (like map<) are deprecated and will go away to be replaced with applying transducers to channels.





[ALGOM-12] Add new monad tutorial links to README Created: 14/Feb/14  Updated: 21/Feb/14  Resolved: 21/Feb/14

Status: Resolved
Project: algo.monads
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Major
Reporter: Leonardo Borges Assignee: Konrad Hinsen
Resolution: Completed Votes: 0
Labels: documentation, enhancement

Attachments: Text File 0001-Add-new-monad-tutorial-links.patch    
Patch: Code

 Description   

This patch adds the monad tutorials I wrote a while back.

It was requested by a user in this tweet: https://twitter.com/JakeGoulding/status/434309278329872384

Since he doesn't have a CA on file, I just created the patch myself.



 Comments   
Comment by Konrad Hinsen [ 21/Feb/14 8:15 AM ]

Done: https://github.com/clojure/algo.monads/commit/11429c1c05c2c0aa4d4befd783efa66748a40b1b





Generated at Wed Oct 22 19:59:13 CDT 2014 using JIRA 4.4#649-r158309.