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
nction composition is the norm.
Clojure is certainly young enough for new conventions to emerge,
especially with some buttressing from documentation tools.
Best -- Eric
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, se
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
of Actionscript coding, I fell in love
>>>> with Natural Docs (http://www.naturaldocs.org/) and this is really the
>>>> kind of thing I would most enjoy using if I'm going the route of
>>>> automatically extracting comments and doc strings, because it gives
&
thread about Literate Programming,
including org-babel and Mark Fredrickson's changeling lein plugin,
which also raised interesting possibilities. So I'm guessing a lot of
people are interested in versatile doc tools and are working on and
exploring the options.
So this seems like a
gt;> looking for. Recently, there was a thread about Literate Programming,
>> including org-babel and Mark Fredrickson's changeling lein plugin,
>> which also raised interesting possibilities. So I'm guessing a lot of
>> people are interested in versatile doc tools
Mark Fredrickson's changeling lein plugin,
which also raised interesting possibilities. So I'm guessing a lot of
people are interested in versatile doc tools and are working on and
exploring the options.
So this seems like a good time to ask: what is the current
state-of-the-art in C
od time to ask: what is the current
state-of-the-art in Clojure documentation tools?
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are
24 matches
Mail list logo
