Minor issue. My bad. It counts lines in the var list, and I implemented the grouping with new lines for the object types without noticing this.

Can defmulti or defmethod symbols have doc strings? Examples? If not, should they be enhanced to do so?

This can be done by prepending the string "(?i)" to the regex entered by the user. They could do this themselves, but I suspect lots of people would prefer this to be the default. We could have a new checkbox menu item under Vars, "Case-sensitive filtering", if anyone really prefers case-sensitive for some searches.

Similar to "Search docs also" option that exists now. Also "Search examples also", but that is really only easy to implement when in ClojureDocs offline mode.

Examples of what I'd like to see saved and restored across sessions:

• Window size and position
• Font, color coding
• vars-cbx choice
• doc-cbx choice
• Choices of Vars menu, items "Categorized Listing" "Search Docs Also" and "FQN Listing" if and when it is implemented.
• Choice of Clojuredocs Online/Offline
• Probably a few other things, too.

For debugging and working around bugs, should have an option to start up a browser without reading these saved settings, but I think reading and restoring these settings should be the default.

"All" can be a bit overwhelming with all the TYPE / META in the middle. It would be great to have a Doc/Source option to show Doc followed by Source without the other stuff.

get swing html-text widget to work properly and replace the text-area (looks nicer, will have links working, code-highlighting, etc...) - rendering works in stand-alone browser window, but swing-widget doesn't look very nice...

(un)trace all vars within the selected ns

Currently, the only way I see to quit the clj-ns-browser is to exit the repl. There should be a "File --> Quit" menu item to quit/exit it.

Make a new vars-cbx choice "map without clojure.core" that shows only symbols in the map that do not map to something in clojure.core.

Reason: Most namespaces refer to everything in clojure.core. This is nearly 600 symbols. I would guess that for most namespaces, there are relatively few things referred to outside of clojure.core, and it would be nice if the GUI made it easy to show only those things, not everything.

Useful to quickly select all namespaces if user wants to search symbol names and/or doc strings in all namespaces simultaneously.

https://github.com/weavejester/ns-tracker

try different window layout with ns and var list-boxes above doc text-area

It works fine on Mac OS X 10.6.8 and Ubuntu 11.10. Should probably use Java java.io.File class methods like exists, and platform-specific path name separators, instead of shell [ -f filename ] test.

Nothing terribly specific here now -- just some summarized, perhaps even mangled by my bad memory, feedback from the audience at the Bay Area Lisp meetup:

Embrace and extend the techniques of people who do "Search Driven Programming", i.e. Google with the right keywords when you run across a problem. We won't be replacing Google, but we can provide tips on better search terms to use that get more focused results, e.g. " +clojure site:stackoverflow.com", and perhaps even send those terms to Google in their web browser for them.

Make it more social. Find out who wrote the examples so you can ask them a question? The data to do this might already be available on ClojureDocs.org.

I think it would be better to filter on the complete fqn if the fqn is listed - more consistent and more flexible

My addition of the choice search-all-docs in the Vars menu is kind of a hack. It would be more orthogonal if there was a check box labeled something like "Also search doc string".

When that box was not checked, then any regex pattern typed into the text box above the vars list would be used to match against the symbol names only.

When the box was checked, the regex pattern would be matched against the symbol names and the doc strings.

Another possibility is to have yet another check box to enable searching for regex matches within the ClojureDocs examples or comments.

When selecting only namespace clojure.core, selecting symbol / shows documentation correctly. However, when selecting more than one namespace, selecting symbol clojure.core// does not work. Probably related to (symbol "clojure.core//") call somewhere. If so, calling better-symbol instead might fix it.

Example: Select namespace clojure.java.browse with categorization on, and vars-cbx with "imports" selected. Symbol URI is shown under category (nil) instead of java.lang.Class like most imported classes are.

This occurs because the symbol URI is in the ns-map of namespace clojure.java.browse, but it is not in the map of the current namespace ns when the function (clj-info.doc2map/get-docs-map 'URI) is called (which in turn calls (clj-info.doc2map/docs-map 'URI)) to look up the documentation for the class. Given that we can select multiple namespaces at once, and perhaps different namespaces could have different symbols 'URI mapping to different Java classes (TBD: possible? Test case?) it seems like we would need a way to pass the namespace in addition to the symbol to properly resolve these, and use (ns-resolve ) instead of (resolve ) in the docs-map implementation.

When vars-cbx has "special forms" selected and you select var "dot", the documentation display is bad. Not surprising, since the real symbol name is ".".

same for map

https://github.com/fogus/trammel

"Trammel provides the provide-contracts macro to define contracts and apply them dynamically to existing functions"
http://fogus.github.com/trammel/provide-contracts/index.html

Wonder if it makes sense to have some predefined contracts that you could easily add as contracts to existing functions - very much like we now add a trace to a fn. The advantage would be that you could narrow down on potential bugs by dynamically reusing contracts to functions to ensure that are called with "correct" parameter values.

Thanks to John Gabriele for reporting this.

I used the browser successfully some time ago, but now when I try to run it, I get

C:\Users\adi> lein repl
Retrieving clj-ns-browser/clj-ns-browser/1.3.1/clj-ns-browser-1.3.1.pom from clojars
Retrieving org/clojure/clojure/1.5.0/clojure-1.5.0.pom from central
Retrieving seesaw/seesaw/1.4.3/seesaw-1.4.3.pom from clojars
Retrieving org/fife/ui/rsyntaxtextarea/2.0.4.1/rsyntaxtextarea-2.0.4.1.pom from clojars
Retrieving clj-info/clj-info/0.3.1/clj-info-0.3.1.pom from clojars
Retrieving org/clojure/clojure/1.5.0/clojure-1.5.0.jar from central
Retrieving clj-ns-browser/clj-ns-browser/1.3.1/clj-ns-browser-1.3.1.jar from clojars
Retrieving org/fife/ui/rsyntaxtextarea/2.0.4.1/rsyntaxtextarea-2.0.4.1.jar from clojars
RetrievingRetrieving  seesaw/seesaw/1.4.3/seesaw-1.4.3.jarclj-info/clj-info/0.3.1/clj-info-0.3.1.jar  fromfrom  clojarsclojars

nREPL server started on port 31539
REPL-y 0.1.9
Clojure 1.4.0
    Exit: Control+D or (exit) or (quit)
Commands: (user/help)
    Docs: (doc function-name-here)
          (find-doc "part-of-name-here")
  Source: (source function-name-here)
          (user/sourcery function-name-here)
 Javadoc: (javadoc java-object-or-class-here)
Examples from clojuredocs.org: [clojuredocs or cdoc]
          (user/clojuredocs name-here)
          (user/clojuredocs "ns-here" "name-here")
user=> (use 'clj-ns-browser.sdoc)
NoSuchMethodError clojure.lang.RT.mapUniqueKeys([Ljava/lang/Object;)Lclojure/lang/IPersistentMap;  clj-ns-browser.sdoc/loading--4920--auto-- (sdoc.clj:9)

This is with lein 2.0.0 under Windows 7, with the browser added to my profiles.clj. Any advice?

Suggestion: At least include everything that appears when you choose "All" under the documentation popup menu. Right now the web page includes Docs and Source, but not Examples, See Alsos, Comments, Class, and Value.

I think it might be best to enable it, and make clicking it have the same effect, regardless of the current doc-cbx choice.

At least in my limited testing on Mac OS X 10.6.8, latest Oracle/Apple JDK 1.6.something as of Apr 4 2012, and IBM JDK 1.6 and Oracle JDK 1.7 on Ubuntu 11.04. All of this was with either clj-ns-browser 1.0.0 release, or perhaps the latest code just before the release after that. I just wanted to record it somewhere before I forgot.

Every alias is specific to a single namespace, so I think it would only be confusing to try to display a mix of aliases from more than one namespace at a time. It would be good in this case to show some kind of message in the Vars list indicating that you should select exactly one namespace to see its list of aliases.

The one example I've seen is clojure.core/print-level

Its first line in the documentation panel when I choose "All" is:

clojure.core/print-length - Var => nil

The type/value section shows up as follows:

TYPE: class clojure.lang.Var

@type:

VALUE:

<Var@2f60877b: 32>

The source code is this:

SOURCE:
(def ^:dynamic
^{:doc "print-length controls how many items of each collection the
printer will print. If it is bound to logical false, there is no
limit. Otherwise, it must be bound to an integer indicating the maximum
number of items of each collection to print. If a collection contains
more items, the printer will print items up to the limit followed by
'...' to represent the remaining items. The root binding is nil
indicating no limit."
:added "1.0"}
print-length nil)

Everything in the display is consistent with the initial value of nil, except the VALUE is shown as the integer value 32. I think what might be happening here is that print-level is dynamically bound using a 'binding' call somewhere in the REPL initialization code to 32, and somehow the browser code for printing the value is picking up that dynamic binding, but the browser code for printing the type is not. I haven't investigated yet to figure out why that would be, but it would be nice if they were consistent with each other.

It would be very nice if we could somehow show the different values that a dynamic var can have in different JVM threads, but that is a separate and probably much more difficult issue.

I don't know if this would be desirable by users, or if it would be difficult to implement.

If a user had a relatively small project, many of the namespaces they see in the browser may only show up because of their use of clj-ns-browser. It might be nice if they could hide those with a checkbox menu item.

One potential difficulty implementing this idea is to determine whether a namespace appears only because it is used by clj-ns-browser, but not also by the user's project. For example, a user's project might use the namespace seesaw.core just as clj-ns-browser does, and choosing to hide namespaces used only by clj-ns-browser should not hide seesaw.core in that case.

see if tools.namespace could be enhanced to get the (jar)file-name associated with a ns, which could give an indication of the version also (?)

The docs for ns in clj-ns-browser don't include:

"A clojure.lang.Namespace object representing the current namespace."

Instead, in clj-ns-browser, it says:

"Fundamental library of the Clojure language"

For example, currently, the docs for clojure.core/apply look like this:

clojure.core/apply   -   Function

[f args][f x args][f x y args][f x y z args][f a b c d & args]
  Applies fn f to the argument list formed by prepending intervening arguments to args.
Refs: 
  http://clojuredocs.org/clojure_core/clojure.core/apply

where I think they would be more readable as:

clojure.core/apply   -   Function

[f args][f x args][f x y args][f x y z args][f a b c d & args]

  Applies fn f to the argument list formed by prepending intervening arguments to args.

Refs: 
  http://clojuredocs.org/clojure_core/clojure.core/apply

or perhaps even:

clojure.core/apply   -   Function

[f args]
[f x args]
[f x y args]
[f x y z args]
[f a b c d & args]

  Applies fn f to the argument list formed by prepending intervening arguments to args.

Refs: 
  http://clojuredocs.org/clojure_core/clojure.core/apply

similar to how they're displayed at http://clojuredocs.org/clojure_core/clojure.core/apply.

(Wishlist: Eventually though, it would be nice if the actual docstrings were markdown-formatted, such that they could be formatted as html for display.)

So it is easier to turn them into links, or copy/paste them as desired.

These are categorized as Var by get-docs-map, but is there a way they could instead be categorized as Function? clj-http.core/proxy-delete-with-body and proxy-get-with-body. It looks like the extension of the docsmap protocol for type clojure.lang.Var in clj-info's doc2map.clj is categorizing those as Vars rather than Functions because either they have no metadata, or if they do, their metadata has no value for the key :arglists.

Minor issue: I can compile fine using "lein uberjar" on Ubuntu 11.10 with Oracle JDK 1.7 but only by commenting out the :jvm-opts line in project.clj. If there is a way to make parts of project.clj OS or JDK-dependent, that would be nice to have in there.

Right now the value only shows up as the pprint'ed value of the atom or ref itself. Do a deref and pprint the value, too, in these cases. Does it make sense to do this for agents as well?

This might complicate the behavior too much, but imagine letting the user select an arbitrary subset of the namespace names. The symbols shown in the var list to its right would be those symbols in all of the selected namespaces. To make it easy to select all namespaces, there could be a "Select All" button above the namespace list.

If this were done, then the menu item "all-publics" in the Vars menu should be removed, as it would be redundant. Similarly for "search-all-docs", but see also Issue #11 related to that menu item.

On Windows 7, JDK 1.7.0_07 64-bit, closing clj-ns-browser's main window by clicking the [X] button on the window (or Alt-F4) always results in a message dialog that says:

"Sorry... cannot close/hide the last browser window."

Consider changing vars with category Protocol so that VALUE does not show up as a map, and "Inspect Coll" button is disabled.

At the Bay Area Clojure meetup last Thu in SF, there were many animated discussions about the clj-ns-browser with a lot of constructive ideas for enhancements.

One stinging criticism that was brought up though, and that had almost full consensus among the 20-30 clojurians present, was that the name ""Clojure Namespace Browser" sucked... and was not considered to be very imaginative, catchy, and certainly not fitting for a cool tool like the clj-ns-browser.

Unfortunately, no good alternatives were found during the meetup... and FrankS ended up offering a good bottle of wine to anyone who could come up with the right name for the browser.

Please use this issue-thread for your suggestions!

looks kind of ugly... should be bigger, other font...other kind of tree-widget may look nicer

maybe should be shown in the doc-panel

One could imagine going as far as having a progress bar type display like web browsers do when downloading files, but that is probably too much implementation complexity unless there is a widget already on the shelf that can be used for it.

I think at a minimum, though, it would be good to pop up a window quickly indicating that the downloading has begun, so the user knows something is happening.

ie. got to clojure.set join
click Source button, notice the syntax highlighting is on, then Ctrl+click Doc, the syntax colours are gone, now drag any one of the buttons like 5 pixels and release this will make the syntax highlighting to activate while the pressed buttons appear depressed but they are still in effect in the doc text (aka both source and doc are still in the doc text below). But now, click on the next(or any) map-invert (without pressing any of the buttons like Source/Doc) will keep the join doc on. So this is basically the second "bug".

right now the vars are categorized by macro/function/etc., which is a good option, but not always the most convenient one.

Maybe we should have a choice to show them in one list, or show them categorized. (popup menu choice? radio button above/below? menubar-menu choice?)

Categorized display could also be a tree-widget.

Same is true for showing only the local name or the fqn - maybe another choice for every display to show list as local- or fq-name.

Same is true for public and private - either radio- of choice-button choice.

Or maybe show list in a table with local, fqn, public/private indicator, macro/function indicator, maybe color-code rows (red for macros).

Too many choices... too little time...

On Lubuntu 12.04, with Leiningen 2.0.0-preview4 on Java 1.6.0_24 OpenJDK 64-Bit Server VM, using Clojure 1.4.0, when I click the Browse button, the resulting java/swing window that pops up contains unreadably-tiny text.

My default browser is Firefox, so I'd assume that the Browse button would cause a new tab to open in the front-most Firefox window.

Also though, since the clj-ns-browser window Doc text area already contains the relevant clojuredocs url, I can just copy/paste that url into a new browser tab and visit the clojuredocs page that way. So, I'm not sure how useful the Browse button is. Maybe should the browse button be removed?