Fair points. Well, leaving the possibility to document the code from just 
anywhere is what I had in mind.

Le samedi 26 avril 2014 22:52:41 UTC+2, Jason Felice a écrit :
>
> Personally, I like documentation in the same place as the code it 
> documents.... And I'd love to have the  tests in the same file as well.
>
> In both cases, I think the things are highly coupled by their nature, and 
> therefore I want them together (OK, tests aren't always - in the cases they 
> aren't, put them in a separate file).  I've reminded people that the SRP 
> ("any piece of code should have one reason to change") implies the 
> converse, which I phrase as "Code which changes together, stays together."
>
> That said, I like the idea of more structured documentation.  (Possibly 
> including test cases!  Python has test runners which verify examples in doc 
> strings, for example.)
> On Apr 26, 2014 4:31 PM, "Gary Trakhman" <gary.t...@gmail.com<javascript:>> 
> wrote:
>
>> This is a lovely idea. 
>>
>> I think prismatic schema is one well-accepted way to document data 
>> shapes, but it's expected to be used inline. It would be nice to have 
>> flexibility in what description systems are used in addition to flexibility 
>> of where the docs live. 
>>
>> I agree that being able to see and reason about bare code with no hassle 
>> is a (personal) demotivator for documentation, but where the docs live 
>> should be up to the implementor.  Having a code-based system means we can 
>> use and improve existing runtime tooling to navigate and interact with it. 
>>  This would make a great cider middleware :-).
>>
>> On Saturday, April 26, 2014, Val Waeselynck 
>> <val.v...@gmail.com<javascript:>> 
>> wrote:
>>
>>> Hello to all,
>>>
>>> *Short version :* I think Clojure needs a documentation system in 
>>> Clojure, I would like to know if some efforts exist in that direction, and 
>>> I am willing to create it / contribute to it.
>>>
>>> *Long version :*
>>>
>>> I've been thinking for a while that the Clojure community could benefit 
>>> a lot from a more sophisticated and ergonomic documentation system. 
>>>
>>> I have seen some existing plugins like lein-sphinx, but I think it would 
>>> be really good to have documentation that would be written in Clojure, for 
>>> the following reasons :
>>>
>>>    - we're all very fond of Clojure data structures and their syntax. 
>>>    (I don't know about you, but I find that even HTML looks better in 
>>>    Clojure <https://github.com/weavejester/hiccup> than in HTML). Plus, 
>>>    Clojure programmers already know how to edit them.
>>>    - (better reason) The facts that Vars are first-class citizens and 
>>>    that symbols can be referred explicitly with hardly any ceremony 
>>> (macros) 
>>>    are a exceptional opportunity to make smart and highly-structured 
>>>    documentation very easily. 
>>>    - if it's in Clojure, Clojure programmers can seamlessly build *ad 
>>>    hoc* documentation functionality on top of it to suit their own 
>>>    particular needs.
>>>
>>> I haven't found anything of the like yet, and if it exists, I would be 
>>> grateful if someone would redirect me to it.
>>>
>>> Here are *my thoughts on this :*
>>>
>>>    1. Clojure doc-strings, although they are quite handy as reminders 
>>>    and for doc-indexation, are *too raw a content*. Even when they are 
>>>    done right, they tend to be cumbersome, and it's too bad to have such 
>>>    concise code drown in the middle of so much documentation. What's more, 
>>> I 
>>>    believe that when programmers program a function (or anything), they 
>>> tend 
>>>    to think more about the implementation than the (uninformed) usage, so 
>>> they 
>>>    have little incentive to make it right.
>>>    2. Building on 1. having a system where documentation and programs 
>>>    live in separate files, in the same way as tests, would enforce a 
>>> healthy 
>>>    separation of concerns. Importantly, it would make life much easier on 
>>> the 
>>>    Version Control perspective. 
>>>    3. Documentation should probably be made differently than what 
>>>    people have got accustomed to by classical languages. Because you seldom 
>>>    find types, and because IMHO Clojure programs are formed more by 
>>> factoring 
>>>    out recurring mechanisms in code than from implementing intellectual 
>>>    abstractions, the relevant concepts tend not to be obvious in the code. 
>>>    Since in Clojure we program with verbs, not 
>>> nouns<http://steve-yegge.blogspot.fr/2006/03/execution-in-kingdom-of-nouns.html>,
>>>  
>>>    I think *documentation is best made by example*.
>>>    4. Documentation of a Var should not be a formal description of what 
>>>    it is and what it does with some cryptically-named variables. *Every 
>>>    bit of documentation should be a micro-tutorial*. Emphasis should be 
>>>    put on usage, examples, tips, pitfalls, howtos. 
>>>    5. There should be structure in the documentation, and it shouldn't 
>>>    be just :see-also links - *there should be semantics* in it.  For 
>>>    example, some functions/macros are really meant to be nothing but 
>>>    shorthands for calling other functions : that kind of relationship 
>>> should 
>>>    be explicitly documented. 
>>>    6. Documentation should not be just information about each separate 
>>>    Var in a namespace. There should be a hierarchy to make the most useful 
>>>    elements of an API more obvious. Also, adding cross-vars documentation 
>>>    elements such as tags and topics could make it easier to navigate and 
>>>    understand. 
>>>    7. *Documentation in the REPL is great*, it was one of the very good 
>>>    surprises when I started learning Clojure. However, a rich and 
>>> good-looking 
>>>    presentation like in Javadocs would be welcome too.
>>>    
>>> Of course, all of the above are just vague principles. Here is *some 
>>> functionality I suggest for a start :*
>>>
>>>    1. Documentation content elements could be written in a Clojure DSL 
>>>    emulating some kind of docbook-like markup language.
>>>    2. On the user side, the documentation would be accessible through a 
>>>    generated web interface, a REPL interface, and maybe other formats like 
>>>    Wiki. 
>>>    3. Documentation could be programmed anywhere in a project by simply 
>>>    referring to the relevant Vars and calling the documentation API. 
>>> Ideally, 
>>>    there would be a dedicated folder for documentation files, and a 
>>> Leiningen 
>>>    plugin to compile them and generate the HTML from them.
>>>    4. I often find myself lost because I have no idea what shape some 
>>>    arguments to a function should have, such as config maps and maps 
>>>    representing application-specific models. To adress this, I propose to 
>>>    explicitly declare and describe *"stereotypes"* in the 
>>>    documentation. Such stereotypes could be, for instance, "JDBC 
>>> connection" 
>>>    or "Ring middleware". From what I have seen, some good 
>>> work<https://github.com/prismatic/schema>has already been done in that 
>>> direction, but it would be good to make room 
>>>    for it in documentation. 
>>>    5. Weigh the documentation contents by importance, to allow for 
>>>    displaying the documentation with several levels of details.
>>>    6. Cross-vars, semantic documentation with *topics*, *tags*, and 
>>>    *links*. *Topics* would group several API elements together to 
>>>    explain a technique or concept; they could have a 
>>> :prerequisiterelationship to help the reader navigate them. I imagine 
>>>    *tags* giving hints on various aspects of a Var, such as :curriedfor a 
>>> function, or 
>>>    :utility, or :use-with-caution, etc. *Links* could be such things as 
>>>    the famous :see-also, but could also represent more precise 
>>>    relationships, such as :calls-to, :often-used-with, :similar-to, etc.
>>>    7. In addition to small, Var-specific, self-contained code samples, 
>>>    there could be larger examples (e.g sample applications), and pointers 
>>> from 
>>>    the documentation to specific points in these examples.
>>>    8. There could be other types of documentation than just static 
>>>    description, such as exercises, koans, quizzes, etc. 
>>>
>>> I would like to know what work has already been done in that direction, 
>>> and if you agree that this is useful, I am willing to help design and 
>>> implement it.
>>>
>>> Your reactions are very welcome.
>>>
>>>
>>> Bests,
>>>
>>> Valentin Waeselynck.
>>>
>>>
>>>  -- 
>>> 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 moderated - please be patient with 
>>> your first post.
>>> To unsubscribe from this group, send email to
>>> clojure+unsubscr...@googlegroups.com
>>> For more options, visit this group at
>>> http://groups.google.com/group/clojure?hl=en
>>> --- 
>>> You received this message because you are subscribed to the Google 
>>> Groups "Clojure" group.
>>> To unsubscribe from this group and stop receiving emails from it, send 
>>> an email to clojure+unsubscr...@googlegroups.com.
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>>  -- 
>> 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<javascript:>
>> 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 <javascript:>
>> For more options, visit this group at
>> http://groups.google.com/group/clojure?hl=en
>> --- 
>> You received this message because you are subscribed to the Google Groups 
>> "Clojure" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to clojure+u...@googlegroups.com <javascript:>.
>> For more options, visit https://groups.google.com/d/optout.
>>
>

-- 
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 moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to