Namespace Docstrings?

[OGINO Masanori]

Hello.

What is the right way to display namespace docstrings?

One day, as usual, I typed:

(doc 'clojure.core) ; or other namespace

Then the REPL said "clojure.lang.Cons cannot be cast to clojure.lang.Symbol."
I thought "Ah, I know, the message means "(quote clojure.core) cannot
be cast to the symbol clojure.core." I'm wrong." and typed:

(doc clojure.core)

Then the REPL said "ClassNotFoundException clojure.core."
I thought "Indeed, clojure.core seems to be an class name...
Precisely, can (doc) display namespace docstrings?" and typed:

(source doc)

Oh, (doc) uses (find-ns), so (doc) should display namespace docstrings. But how?
Finally I wrote (:doc (meta (the-ns 'clojure.core))) but I know this
is a wrong way.
When I forget this ad-hoc solution, I'll repeat above.

I determined to ask it because I have repeated again just now and I'm annoyed.
Any thought?

Thanks.

--
Name: OGINO Masanori (荻野 雅紀)
E-mail: masanor...@gmail.com

[MHOOO]

I'd say that is a bug.
On clojure 1.3 "resolve" throws an error when passed a symbol naming a
namespace. That is why clojure.repl/doc throws an exception already
during macro invocation & the last cond within it, which checks for
namespaces, never gets evaluated.
So your work-around is what I'd use: or write a patch :?)

> E-mail: masanori.og...@gmail.com

[OGINO Masanori]

Hello.

MHOOO, thank you.
Sorry, for long time I haven't used 1.2, so I forgot checking 1.2.1!
Yes, I use 1.3b1. Sorry for my unkindness.

Since I haven't sent a CA yet, maybe it's not time to send a patch.
However, IMO it's not an issue of (resolve), because (resolve) throws
even if 1.2.1 and (resolve) can resolve classes.

(resolve 'String)

So all we should do is put (find-ns) pair before (resolve) pair, I think.
Could any developer review? Or already fixed in master?

Thanks.

--
Name: OGINO Masanori (荻野 雅紀)

E-mail: masanor...@gmail.com

[OGINO Masanori]

Well, with my solution, namespace's docstring is shown when the same
name exists both in vars and namespaces.

So it seems better to remain (doc) and wrap the body of (ns-resolve) by

(try
...
(catch Exception e nil))

because (ns-resolve) docstring says "else nil", though it actually
throws an exception!

[Rasmus Svensson]

2011/7/14 OGINO Masanori <masanor...@gmail.com>:

'doc' is only used for things that are vars (functions, and other
globals). Namespaces are not vars, so you cannot use 'doc' with them.
To see the docs for a namespace, use the 'print-namespace-doc'
function:

(print-namespace-doc 'the.name.space)

// raek

[Alan Malloy]

On Jul 15, 3:10 pm, Rasmus Svensson <r...@lysator.liu.se> wrote:
> 2011/7/14 OGINO Masanori <masanori.og...@gmail.com>:

This is not true in 1.2.x: (doc clojure.core) works fine for me. If it
stopped working in 1.3 intentionally, that's fine (I guess?), but it
sounds like it was an accident.

[OGINO Masanori]

Hello.

Thank you for giving your opinion, Rasmus.

Indeed, (doc doc) says, "I am for a var or special form."

However, according to (source doc), there is some code for namespace,
and this code won't be used since (ns-resolve) breaks its promise.
Moreover, with 1.2.1, (doc) uses (print-namespace-doc) internally!

And... I hesitate to say but... (print-namespace-doc) seems to be
removed in 1.3.
So I think we also should update docstring of (doc), right?

[OGINO Masanori]

I search on JIRA, but as far as I know there is no issue discussed in
this thread.
Is it an issue that (resolve 'clojure.core) throws an exception?