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/collect_info.clj#L13 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 <tass...@member.fsf.org> 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 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
