It is pretty easy to make a library that modifies doc metadata on existing
vars, e.g.:
https://github.com/jafingerhut/thalia
The time-consuming part, which I am nowhere near completing myself, is
writing the alternate documentation strings. Congrats to anyone that
produces something that becomes widely used.
I would suggest doing whatever suits your fancy in this area, preferably
with no support required, nor roadblocks in the way of what you plan to do,
from clojure.core. Don't be surprised if all your rallying efforts lead to
a team of size one :-)
Andy
On Sat, May 10, 2014 at 7:09 AM, Timothy Baldridge <tbaldri...@gmail.com>wrote:
> If you plan on having this documentation apply to clojure.core.* you'll
> probably want to pull in Alex Miller or start a conversation in
> clojure-dev. I'd hate to see a bunch of decisions made, just to find out
> that Rich has a completely different view, a view that might have been nice
> to know before plans were finalized.
>
> Or perhaps a metadata modification system can be created? One that allows
> people to import clojure libs that adds new doc data to existing vars?
>
> Timothy
>
>
> On Sat, May 10, 2014 at 7:44 AM, Val Waeselynck <val.vval...@gmail.com>wrote:
>
>> Here
>> :<https://docs.google.com/spreadsheets/d/1HyS9qstgEqmdv0MtDm3xEsImnDjCYQhar1PQP3fzwMc/edit?usp=sharing>I
>> think it would help if we had a panoramic view of the existing
>> documentation systems and what we could borrow from them. I could only
>> think of a Google Drive spreadsheet for this, but if anyone has a better
>> idea... :)
>>
>> So it would be nice if people who are knowledgeable about other doc
>> systems could contribute to it. From what I see, that may involve Tim for
>> Emacs, Sean for reStructured, and Daniel for docco, for example?
>>
>> Thanks in advance!
>>
>> Le samedi 26 avril 2014 18:39:04 UTC+2, Val Waeselynck a écrit :
>>
>>> 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.
>>
>
>
>
> --
> “One of the main causes of the fall of the Roman Empire was that–lacking
> zero–they had no way to indicate successful termination of their C
> programs.”
> (Robert Firth)
>
> --
> 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.
