Discrepancies between boot.clj and API Docs

[Meikel Brandmeyer]

Hello Rich,

I noticed a difference between boot.clj and the API Docs. I know that
there are internal definitions, which are not supposed to be used by the
user. New functions might also take some time, before they show up in
the docs.

But I'm missing for example delay and force. I found myself implementing
a Promise class to do exactly this! While working on VimClojure I
found out
by accident that there is a force and hence a delay. That could have
saved
me some time...

I understand that you don't want the docs to be open for public editing.
But maybe we can install a process so that people can easily access the
source for the docs (eg. via SVN repo), write a patch and submit it to
you. You can review it and push it finally to the website if you agree
or request changes or reject the patch completely.

This would be a compromise between you doing all the work and public
editing. (And it would free some time for you to concentrate on Clojure
itself. :))

I think clojure.org should stay a moderated and authoritative resource
for the docs. But it should be up-to-date even when the available
functions still change.

Just some thoughts...

Sincerely
Meikel

[Rich Hickey]

The API docs are generated from the source, so there's nothing there
you can't get from the source. Generally, the site corresponds to a
release. Sometimes things change between releases and I don't want to
make interim promises in the API docs that might not be stable/final.

So, when working from SVN, you should use functions like find-doc, doc
and ns-publics.

Rich

[Meikel Brandmeyer]

Hello Rich,

Am 01.09.2008 um 04:04 schrieb Rich Hickey:

> The API docs are generated from the source, so there's nothing there
> you can't get from the source. Generally, the site corresponds to a
> release. Sometimes things change between releases and I don't want to
> make interim promises in the API docs that might not be stable/final.
>
> So, when working from SVN, you should use functions like find-doc, doc
> and ns-publics.

Ok. That makes sense. I will also have a deeper look in boot.clj. I have
no problem with adapting to changing APIs. I did this with
clojure-contrib.lib anyway. :)

Sincerely
Meikel