why indent multi line docstrings?

[travis]

I disagree with "Indent each line of multi-line docstrings." This results in extra spaces inserted at arbitrary intervals in the resulting string, making docstring maintenance more of a pain - if I'd like to insert text I'll likely need to update a number of other lines lower down in the docstring. Even without this spacing I'd likely need to update line breaks, but updating the spacing feels like an unneeded additional hassle.

Certainly open to other thoughts, but I'm curious about the justification for this rule...

[jeremyheiler]

Formatting a docstring in Emacs preserves the indentation while adjusting the line breaks. I'm not trying to defend the practice, I'm just saying that one particular editor makes it easy to do.

[travis]

hm, I actually use emacs and haven't noticed that: one example:

(defn foo
  "Topping sugar plum cupcake liquorice macaroon. Apple pie pie oat
   cake tootsie roll liquorice jelly-o jelly-o icing powder. Chocolate
   cake dragée marzipan liquorice soufflé jelly jelly beans fruitcake
   oat cake."
  :foo)

If I add text and then hit enter to create a new line break this becomes:

(defn foo
  "Topping sugar plum cupcake liquorice macaroon. Apple pie pie oat
   cake tootsie roll liquorice bacon bacon bacon bacon bacon bacon jelly-o
 jelly-o icing powder. Chocolate
   cake dragée marzipan liquorice soufflé jelly jelly beans fruitcake
   oat cake."
  :foo)

I'm assuming my emacs-fu needs some upgrading here - what do you mean when you say "formatting a docstring"?

[jeremyheiler]

I mean hitting M-q (I'm not sure which mode that comes from, though) when the cursor is within the docstring. Sometimes you'll have to manually break and indent the second line so that Emacs knows where to maintain the indentation for the following lines.

[travis]

Hot damn that's beautiful, though at least for me it looks like it's M-q:

(defn foo
  "Topping sugar plum cupcake liquorice macaroon. Apple pie pie oat
   cake tootsie roll liquorice bacon bacon bacon bacon bacon bacon
   jelly-o jelly-o icing powder. Chocolate cake dragée marzipan
   liquorice soufflé jelly jelly beans fruitcake oat cake."
  :foo)

So yea, that's definitely nice for emacs users, though I will note that all of my coworkers aren't emacs folks. I do wonder if this style makes it more complicated to write documentation generators, but I suppose they all probably deal with this case pretty well?

[jeremyheiler]

You're right. I corrected the command in my reply.

That's a good question, as I have been wondering the same thing. I imagine the logic is something along the lines of trimming all whitespace at the beginning of a line.

[tranchis]

In the style guide the following is stated:

;; good
(defn foo
  "Hello there. This is
  a multi-line docstring."
  []
  (bar))

;; bad
(defn foo
  "Hello there. This is
a multi-line docstring."
  []
  (bar))

Which is fine, but I tend to prefer this form, and if I'm correct, I've seen it used more often:

;; good or bad?
(defn foo
  "Hello there. This is
   a multi-line docstring.
   Subsequent lines start
   on the column after the first \""
  []
  (bar))

Is there a chance that we can get both as "good" on the style guide?

[Gonzih]

You are right that this version is used more often. I can see that it is default indention in vim for clojure. But:

(defn foo
  "I don't do a whole lot.
   But At least I'm properly Indented
   Right?"
  [x]
  (println x "Hello, World!"))

And in repl:

 (doc a.core/foo)
-------------------------
a.core/foo
([x])
  I don't do a whole lot.
   But At least I'm properly Indented
   Right?

And you can see one unnecessary space at the beginning of every line (except first one). But I'm agree that it looks nicer while editing code. Not sure what is "the right way" here.

[andreyorst]

I know that the thread is extremely old, but I guess people still hit it occasionally, so some explanations of why docstrings are indented would be good. Especially since there's no explanation of this in the style guide itself.

In Clojure's source code we can see, that print-doc in the repl.clj file inserts one space before the docstring, and println implicitly inserts second space between its arguments:

user> (with-out-str (println " " "docstring"))
"  docstring"
user> (with-out-str (println " " "multiline
  docstring"))
"  multiline\n  docstring\n"

Since the doc is printed as is, e.g. not split into separate lines, if it has multiple lines, we indeed have to add exactly two spaces before each to match this (println " " doc) behavior. Because documentation is often explored in the REPL, and the behavior of print-doc is kinda set in stone, i believe that the right way is to write documentation it in a way that repl.clj expects, e.g. with each line indented with two spaces.