Documentation lacking for ns macro
Ken Wesson
at the main Clojure site does not go into detail about its syntax;
"doc ns" comes closer, with:
(ns foo.bar
(:refer-clojure :exclude [ancestors printf])
(:require (clojure.contrib sql sql.tests))
(:use (my.lib this that))
(:import (java.util Date Timer Random)
(java.sql Connection Statement)))
given as an example. But what exactly, for instance, is the use clause
really supposed to look like? Is that a list of libraries starting
with my.lib, for example, or is it a single lib and a list of symbols?
The accompanying text only suggests looking at the use function's
documentation. But using "doc use" gives:
clojure.core/use
([& args])
Like 'require, but also refers to each lib's namespace using
clojure.core/refer. Use :use in the ns macro in preference to calling
this directly.
'use accepts additional options in libspecs: :exclude, :only, :rename.
The arguments and semantics for :exclude, :only, and :rename are the same
as those documented for clojure.core/refer.
Yeah, that's a real help if you're trying to remember the syntax. "&
args". How specific. :)
I think this is one area that could definitely use improvement,
including a couple of actual examples of usage on the Namespaces page
and a better description of the arglist for the use function (and
ditto require) as well as a better :use example in "doc ns". The model
here should be the example :import clause above, which is perfect --
it's clear that it should be followed by lists that start with a
package and continue with classnames from that package. By contrast,
it's not clear from all of this exactly how to use :use and :require.
Studying (or copying and modifying) example code from elsewhere seems
to be the way to do it and I think it's suboptimal when that's the
ONLY way.
Rasmus Svensson
> The ns macro seems to be poorly documented as yet. The Namespaces page
> at the main Clojure site does not go into detail about its syntax;
Yes. The docs related to the ns form are indeed insufficient and need attention.
However, have you seen the http://clojure.org/libs page? I think it
will answer *some* of you questions. That page isn't perfect, but it
seems to contain the kind of examples you are looking for.
// raek
Ken Wesson
I've seen it, but not especially recently. It's not the obvious place
to look for such, I'm afraid.
Paul Barry
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
Aaron Cohen
> ([& args])
> Like 'require, but also refers to each lib's namespace using
>
> Yeah, that's a real help if you're trying to remember the syntax. "&
> args". How specific. :)
>
You stopped one indirection short, try (doc require).
It's probably a matter of taste how often the documentation should
repeat itself and how often it should refer you to somewhere else. I
agree that a couple of more examples would be nice though.
Ken Wesson
> On Thu, Nov 4, 2010 at 2:41 PM, Ken Wesson <kwes...@gmail.com> wrote:
>>
>> clojure.core/use
>> ([& args])
>> Like 'require, but also refers to each lib's namespace using
> ...
>>
>> Yeah, that's a real help if you're trying to remember the syntax. "&
>> args". How specific. :)
>
> You stopped one indirection short, try (doc require).
I have an HTL of 1. If I get referred elsewhere a second time I get annoyed. :)