Tom- Definitely helps, I'll add this on the next var update cycle.
Thanks, Zack. On Jul 18, 12:17 pm, Tom Faulhaber <[email protected]> wrote: > What I've noticed is that conventions on doc string indentation is all > over the place. Combine that with the fact that folks build tables and > columns by hand, and a really simplistic rule doesn't work so much. > > I recommend you just grab the remove-leading-whitespace function from > the autodoc program and use it. It's here: > > http://github.com/tomfaulhaber/autodoc/blob/master/src/autodoc/collec... > > That seems to make all the doc strings I've encountered in the wild > format up pretty well. > > HTH, > > Tom > > On Jul 17, 2:52 am, Tassilo Horn <[email protected]> wrote: > > > > > Hi Zack, > > > I just had a look at ClojureDocs.org and it's really neat! > > > Some observations I made: > > > - When I view the docs of let's say clojure.set/rename, the clojure.set > > part is a link. But instead of pointing to to clojure.set summary > > page, it is only http:. > > > - In the source section, not all referenced vars (called functions) are > > linked. > > > - All lines of multi-line docstrings are except the first are indented > > which looks quite ugly. Well, that's not ClojureDoc.org's fault. It > > seems that it's a clojure convention to write docstrings like: > > > --8<---------------cut here---------------start------------->8--- > > (defn my-function > > "Do magic and return a spell. > > More detailed docs... bla bla bla bla bla bla bla bla bla bla bla bla bla > > bla > > bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla " > > [] > > (let [spell (do-magic)] > > (if (castable? spell) > > spell > > (alternative-spell sepll)))) > > --8<---------------cut here---------------end--------------->8--- > > > instead of like > > > --8<---------------cut here---------------start------------->8--- > > (defn my-function > > "Do magic and return a spell. > > More detailed docs... bla bla bla bla bla bla bla bla bla bla bla bla bla > > bla > > bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla " > > [] > > (let [spell (do-magic)] > > (if (castable? spell) > > spell > > (alternative-spell sepll)))) > > --8<---------------cut here---------------end--------------->8--- > > > which is the convention in any other lisp I know. Has this convention > > a reason, or is this only Rich's personal preference others simply > > adapted? > > > Anyway, really neat! :-) > > > Bye, > > Tassilo -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to [email protected] Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/clojure?hl=en
