2010/9/9 Mark Engelberg :
> On Wed, Sep 8, 2010 at 11:56 PM, Laurent PETIT
> wrote:
>>> Full ack here.
>>
>> For the non english speaker I am : is this a pun/playword ? (full ack
>> <-> f..ck all) ?
>
> I assume he meant "full acknowledgment" -- an expression of agreement.
Yes, but since Phil in
On Wed, Sep 8, 2010 at 11:56 PM, Laurent PETIT wrote:
>> Full ack here.
>
> For the non english speaker I am : is this a pun/playword ? (full ack
> <-> f..ck all) ?
I assume he meant "full acknowledgment" -- an expression of agreement.
--
You received this message because you are subscribed to
2010/9/9 Phil Hagelberg :
> On Tue, Sep 7, 2010 at 11:10 PM, Mark Engelberg
> wrote:
>> Files:
>> Many times there are dozens of functions that are interrelated. Only
>> one or two of them are the crucially important "entry points" that
>> provide the high-level API. The rest are mostly helper f
On Wed, Sep 8, 2010 at 1:18 AM, Mark Engelberg wrote:
> I don't know that I'd be flattered by that comparison :)
LOL. Point well taken :)
> If you ever read an article presenting some new algorithm, data
> structure, etc. in an academic journal, the published article will
> certainly contain som
On Tue, Sep 7, 2010 at 11:10 PM, Mark Engelberg
wrote:
> Files:
> Many times there are dozens of functions that are interrelated. Only
> one or two of them are the crucially important "entry points" that
> provide the high-level API. The rest are mostly helper functions that
> implement the lowe
On Wed, Sep 8, 2010 at 12:05 AM, Sean Corfield wrote:
> Most people who read my code have said it reads like poetry...
Poetry takes a complex message and packs it into as few words as
possible, resulting in something so cryptic and enigmatic that people
bicker endlessly about what subtle meanings
As a counterexample to these statements consider proxy, genclass, and
it's ilk ---
I don't think reading the source is good enough to totally understand
the purpose behind those functions.
There's also the issue of providing examples in the doc string.
What's more clear,
"
Associates a value
On Tue, Sep 7, 2010 at 11:10 PM, Mark Engelberg
wrote:
> What pre-conditions need to be met by the inputs?
> What invariants are maintained by the function?
> What are the performance guarantees of the function?
And this can't be expressed in a single sentence?
> Many times there are dozens of f
On Tue, Sep 7, 2010 at 10:23 PM, Sean Corfield wrote:
> I'm watching this thread and I'm wondering what kind of documentation
> people are talking about here. I've always been used to using
> self-documenting function / variable names and short comments for
> documenting everything. Clearly you gu
On Tue, Sep 7, 2010 at 1:25 AM, Mark Engelberg wrote:
> Docstrings seem designed for fairly terse comments about the nature of
> the function. It's great for providing little hints about how the
> function works to jog one's memory by typing (doc ...) in the REPL, or
> for searching with find-doc
Phil Hagelberg writes:
> On Tue, Sep 7, 2010 at 1:25 AM, Mark Engelberg
> wrote:
[...]
>> Javadoc has an interesting property: it considers that the first
>> sentence serves as a summary for the doc. The "sentence" delimiter is
>> just the point in the case of javadoc.
>
> Emacs docstrings work
On Tue, Sep 7, 2010 at 1:25 AM, Mark Engelberg wrote:
> Docstrings seem designed for fairly terse comments about the nature of
> the function. It's great for providing little hints about how the
> function works to jog one's memory by typing (doc ...) in the REPL, or
> for searching with find-doc
Hi,
I'd recommend looking at how plt-scheme solved this problem (see [1]).
They actually defined alternative readers in which either prose or code
can be the default input mechanism (with the other escaped in some way).
I don't know if Clojure's reading system is quite flexible enough to
support s
Perhaps you would be interested in postdoc:
http://github.com/markmfredrickson/postdoc
Postdoc allows structured documentation, runnable examples, and
related items based on namespaced identifiers. One was to allow for
separate files that included the documentation away from the code, so
as not
Hi,
2010/9/7 Mark Engelberg :
> Docstrings seem designed for fairly terse comments about the nature of
> the function. It's great for providing little hints about how the
> function works to jog one's memory by typing (doc ...) in the REPL, or
> for searching with find-doc. But I just don't thin
Docstrings seem designed for fairly terse comments about the nature of
the function. It's great for providing little hints about how the
function works to jog one's memory by typing (doc ...) in the REPL, or
for searching with find-doc. But I just don't think I can fit the
kind of full documentat
Hey Mark,
I don't know of any publicly available tools besides autodoc. My
understanding is that Zack was keeping the source to clojuredocs
closed, at least for now. While I assume his extraction code is in
Clojure, the actual clojuredocs presentation code is a Ruby on Rails
app [1]
Whether autod
Mark-
ATM, autodoc is your best bet for automatically generating
documentation from your source files.
The ClojureDocs lib analyzer codebase is pretty much a ns / var
metadata extraction tool, similar to autodoc. Unfortunately out of
the five requirements you listed [1] we only (automatically) t
On Mon, Sep 6, 2010 at 2:51 AM, Tim Daly wrote:
> The literate programming discussion centered around the question
> "what should be the state of the art in clojure documentation",
> not "what is the state of the art in clojure documentation".
I brought up literate programming as an example of a
Is it feasable to create a literate haskell like alternate format for Clojure?
2010/9/6 Tim Daly :
> See http://en.wikipedia.org/wiki/Axiom_computer_algebra_system
> which is "in process" to become a fully literate computer
> algebra system. 20 volumes so far and a lot of documentation
> still to
See http://en.wikipedia.org/wiki/Axiom_computer_algebra_system
which is "in process" to become a fully literate computer
algebra system. 20 volumes so far and a lot of documentation
still to come.
Once a system gets larger than one person's head (e.g. Rich's)
then the question of "why" becomes in
To have a good idea of how this can work, see Literate Haskell
2010/9/6 Tim Daly :
> The literate programming discussion centered around the question
> "what should be the state of the art in clojure documentation",
> not "what is the state of the art in clojure documentation".
>
> If you're looki
The literate programming discussion centered around the question
"what should be the state of the art in clojure documentation",
not "what is the state of the art in clojure documentation".
If you're looking for API documentation then literate programming
is the wrong tool. An API would document
23 matches
Mail list logo
