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.
