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.trakh...@gmail.com> 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.vval...@gmail.com> 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 :curried for
>> 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 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 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.
