You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
(nstest.core"If I write a really long line without worrying about indentation and then call clojure-fill-paragraph to indent once I'm done it looks like this and all is well.This paragraph on the other hand was created by hitting RET to indent manually. Every time I do this the indentation moves all the way to the left, instead of staying aligned. Calling clojure-fill-paragraph now will indent all but the first line in this paragraph properly.")
@expez The newline/(auto)indentation is tricky in Emacs. I push a PR (#243) so that TAB does the right thing in docstring, but there is no auto-indentation yet. Will have a closer look.
As for whether this should be
"a docstring...
and some more text
or
"a docstring
and some more text"
I don't know. Aesthetically and for consistency with the rest of Clojure indentation I agree, but all the functions in Clojure source code use the "wrong" indentation. The question should be raised on the Clojure mailing list so that everyone can agree on the same convention, don't you think so?
Every function looks like that in the Clojure source because that's what happens when you hit M-q when writing lisp source. Nobody is going to manually indent and expect everyone else to do the same.
That might be an argument in and of itself, though, that this is what you get in emacs lisp or common lisp mode, in emacs, when you hit M-q and since clojure is a lisp we should conform.
The clojure plugin for vim already has a setting, which is off by default, called clojure_align_multiline_strings which does what I propose. Together these two editors have 75% market share so we won't be inconveniencing anyone very much if we change this default, and should in fact expect other less popular editors to conform, especially if the style guide @bbatsov is maintaining is updated. The fact that the vim plugin already has a setting for this indicates that a few people have already thought about this. In fact, the default in Vim might reflect them conforming to us (or rather most existing source code), as most users used Emacs for writing clojure in the very beginning.
@expez the problem with this example you present...
(defnfoo []
"Alignment like this")
(defnbar []
"Instead of this")
is that clojure.repl/doc, Grimoire and other docstring access/manipulation tools account for that missing 1st space. Implementing the 2nd behavior would break existing formatting schemes for no good reason. I realized this behavior existed recently, as my docstring style had been exactly what you propose
(defnf"(λ x) → ⊤ (λ x → y) → ⊤"
([x])
([x y]))
which exhibits exactly this mis-alignment behavior.
So no, I don't think that the 75% market share of emacs and vim together justifies this formatting breaking change. Otherwise 👍 on this, the first line failure to indent really gets on my nerves.
If this doesn't lead to actual breakage in the tools, just moving the alignment problem from the source to the output of the tools, then I'll start using the new default @bzg created--at least for my personal use--and hope it catches on. That way, in a few years, all tools might possibly take this into account and we can be free of this problem. I don't want to wait until the next lisp to fix this :)
@bbatsov is your issue with the implicit two spaces, or that it should be an implicit three spaces or what? The standing behavior seems pretty reasonable to me. I certainly don't want Clojure to try and package a "real" typesetting engine for docstrings 👅
I am having a persistent but somewhat different problem with docstring indentation.
Depending on the content of the docstring (in particular, punctuation), the second line
of a single-paragraph docstring is not indented. The code example below illustrates
the problem and show that it only arises in particular circumstances. One of the
four functions below fills (its docstring) incorrectly, the other three -- with only
slightly varied docstrings -- fill correctly. The results of the filling are given at
the end for each case. I haven't had a chance to trace this problem through the code
yet, but I thought I'd submit the examples. The comment in the code gives details
of the context.
;;; Using M-q inside each of the following three docstrings gives different
;;; behavior, with the second incorrect. Note the period at the end of the
;;; first line makes the difference, though it depends on the line length as
;;; the third example shows. But if the period is there and it starts filled
;;; properly, it stays filled properly, as the fourth example shows.
;;;
;;; platform: Mac OS X 10.7.5
;;; emacs-version: Gnu Emacs 24.4.1 (installed by homebrew)
;;; clojure-mode-version: 3.1.0-snapshot
;;;
;;; paragraph regexps in Emacs set at initialization time by:
;;; (setq paragraph-start paragraph-separate ; Use blank lines to separate paragraphs by default
;;; adaptive-fill-regexp "[ \t]*\\([>*%#]+ +\\)?" ; Fill around comment beginnings and yanked-messages
;;; sentence-end-double-space nil ; Allow frenchspacing
;;; page-delimiter "^\\(\f\\|\n\n+\\)") ; FF or 2+ consecutive blank lines
;;;
;;; Resetting paragraph-start to its original value has no effect.
;;;
;;; fill-prefix is nil and fill-column is 72. Changing the latter has no effect.
;;;
;;; Filling of these examples works fine in analogous defuns in elisp and CL.
(defn fills-right
"Lorem ipsum dolor sit amet, consectetur adipiscing elit sed do ZZZ
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum."
[]
true)
(defn fills-wrong
"Lorem ipsum dolor sit amet, consectetur adipiscing elit sed do ZZZ.
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum."
[]
true)
(defn fills-right-too
"Lorem ipsum dolor sit amet, consectetur adipiscing.
elit sed do ZZZ
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum."
[]
true)
(defn fills-right-stays-filled
"Lorem ipsum dolor sit amet, consectetur adipiscing elit sed do ZZZ.
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum."
[]
true)
;;; Results of filling in these three examples, M-q with point in docstring
(defn fills-right-filled
"Lorem ipsum dolor sit amet, consectetur adipiscing elit sed do ZZZ
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum."
[]
true)
(defn fills-wrong-filled
"Lorem ipsum dolor sit amet, consectetur adipiscing elit sed do ZZZ.
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum."
[]
true)
(defn fills-right-too-filled
"Lorem ipsum dolor sit amet, consectetur adipiscing. elit sed do ZZZ
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum."
[]
true)
As an update, I have a simpler explanation for what is happening. Whenever the first line
of a doc-string ends on a period or comma (with no subsequent spaces), the indentation
of the second line is not changed.
This explains all the examples I showed because in fills-right-too, I inadvertently left
some spaces and in fills-right-stays-filled, the second line is where it should be.
In clojure-fill-paragraph, the variable paragraph-separate has added a regex that includes
a line with optional spaces, quote, and ending with a period or comma, and I wonder if this
is interacting with paragraph-start in such a way to cause the problem. I'll try to look
into it further.
But it still looks like electric-indent-mode is broken? I.e. if I press RET in a Clojure docstring, then point is at column 0 until I press TAB at which point it moves to column 2.
The behavior I see in a docstring with clojure-mode version 5.7.0-snapshot is this one:
RET goes at the beginning of the next line, independantly of electric-indent-mode
C-j indents correctly with electric-indent-mode turned off, but do the same than RET otherwise
The docstring of C-j (aka electric-newline-and-maybe-indent) says:
Insert a newline.
If ‘electric-indent-mode’ is enabled, that’s that, but if it
is disabled then additionally indent according to major mode.
So I'm inclined to think RET and C-j are behaving correctly here, although I too think this is all a bit confusing. I've no good idea right on how to fix this right now.
Also beware that clojure-mode does not recognize docstring after the function's parameters:
(defn a-function
"A well-placed docstring."
[]
nil)
(defn another-function
[]
"A misplaced docstring."
nil)
But the docstring for command newline (bound to RET) says this:
If ‘electric-indent-mode’ is enabled, this indents the final new line
that it adds, and reindents the preceding line. To just insert
a newline, use M-x electric-indent-just-newline.
So your first bullet point sounds like wrong behavior of clojure-mode to me, since if electric-indent-mode is enabled then RET should indent the new line .
Activity
bbatsov commentedon Jul 18, 2014
@bzg is working on this particular feature.
bzg commentedon Jul 19, 2014
Thanks for the heads up.
I'll have a look but can't do it before next week.
bbatsov commentedon Jul 21, 2014
@bzg No worries. Now that we have some unit tests you might add a few for the docstring filling logic as well.
expez commentedon Jul 21, 2014
I also think it would be better if the first char on the second line was aligned with the first char on the first line and not with the
". Like this:This would make it consistent with how the content of a
[ ]is indented. E.g. we do this:and not this, where baz is aligned with
[and notfoo:Thoughts?
bzg commentedon Jul 26, 2014
@expez The newline/(auto)indentation is tricky in Emacs. I push a PR (#243) so that TAB does the right thing in docstring, but there is no auto-indentation yet. Will have a closer look.
As for whether this should be
"a docstring...
and some more text
or
"a docstring
and some more text"
I don't know. Aesthetically and for consistency with the rest of Clojure indentation I agree, but all the functions in Clojure source code use the "wrong" indentation. The question should be raised on the Clojure mailing list so that everyone can agree on the same convention, don't you think so?
expez commentedon Jul 26, 2014
Every function looks like that in the Clojure source because that's what happens when you hit
M-qwhen writing lisp source. Nobody is going to manually indent and expect everyone else to do the same.That might be an argument in and of itself, though, that this is what you get in emacs lisp or common lisp mode, in emacs, when you hit
M-qand since clojure is a lisp we should conform.The clojure plugin for vim already has a setting, which is off by default, called
clojure_align_multiline_stringswhich does what I propose. Together these two editors have 75% market share so we won't be inconveniencing anyone very much if we change this default, and should in fact expect other less popular editors to conform, especially if the style guide @bbatsov is maintaining is updated. The fact that the vim plugin already has a setting for this indicates that a few people have already thought about this. In fact, the default in Vim might reflect them conforming to us (or rather most existing source code), as most users used Emacs for writing clojure in the very beginning.arrdem commentedon Jul 26, 2014
@expez the problem with this example you present...
is that
clojure.repl/doc, Grimoire and other docstring access/manipulation tools account for that missing 1st space. Implementing the 2nd behavior would break existing formatting schemes for no good reason. I realized this behavior existed recently, as my docstring style had been exactly what you proposewhich exhibits exactly this mis-alignment behavior.
So no, I don't think that the 75% market share of emacs and vim together justifies this formatting breaking change. Otherwise 👍 on this, the first line failure to indent really gets on my nerves.
bzg commentedon Jul 27, 2014
I created this PR (#244) which adds an option for this.
expez commentedon Jul 27, 2014
Thanks for pointing that out, @arrdem!
If this doesn't lead to actual breakage in the tools, just moving the alignment problem from the source to the output of the tools, then I'll start using the new default @bzg created--at least for my personal use--and hope it catches on. That way, in a few years, all tools might possibly take this into account and we can be free of this problem. I don't want to wait until the next lisp to fix this :)
bbatsov commentedon Jul 27, 2014
@arrdem I guess we should simply patch
docto handle both styles. The existing default seems pretty odd to me.arrdem commentedon Jul 28, 2014
@bbatsov is your issue with the implicit two spaces, or that it should be an implicit three spaces or what? The standing behavior seems pretty reasonable to me. I certainly don't want Clojure to try and package a "real" typesetting engine for docstrings 👅
genovese commentedon Dec 5, 2014
I am having a persistent but somewhat different problem with docstring indentation.
Depending on the content of the docstring (in particular, punctuation), the second line
of a single-paragraph docstring is not indented. The code example below illustrates
the problem and show that it only arises in particular circumstances. One of the
four functions below fills (its docstring) incorrectly, the other three -- with only
slightly varied docstrings -- fill correctly. The results of the filling are given at
the end for each case. I haven't had a chance to trace this problem through the code
yet, but I thought I'd submit the examples. The comment in the code gives details
of the context.
bzg commentedon Dec 5, 2014
Hi Christopher,
Christopher Genovese notifications@github.com writes:
Sorry, I won't have time to check this particular issue before long, I hope someone else will.
genovese commentedon Dec 5, 2014
Thanks, Bastien.
As an update, I have a simpler explanation for what is happening. Whenever the first line
of a doc-string ends on a period or comma (with no subsequent spaces), the indentation
of the second line is not changed.
This explains all the examples I showed because in
fills-right-too, I inadvertently leftsome spaces and in
fills-right-stays-filled, the second line is where it should be.In
clojure-fill-paragraph, the variableparagraph-separatehas added a regex that includesa line with optional spaces, quote, and ending with a period or comma, and I wonder if this
is interacting with
paragraph-startin such a way to cause the problem. I'll try to lookinto it further.
6 remaining items
bzg commentedon Jan 27, 2015
Hi Tassilo,
I don't have enough time at hand right now -- if you can come up with a patch for this, I'll gladly accept it!
Thanks in advance.
Temporary workaround for docstring indent issue
stig commentedon Jun 10, 2015
I'm having indentation issues on things like this: https://github.com/Datomic/day-of-datomic/blob/master/src/datomic/samples/schema.clj#L50
(Just to add another datapoint.)
Merge pull request #289 from sandhu/master
sandhu commentedon Jun 15, 2015
The #289 PR that got merged this weekend should address this issue.
tsdh commentedon Jun 15, 2015
Great, thanks!
stig commentedon Jun 16, 2015
Hurrah!
De-dent docstring bodies.
Temporary workaround for docstring indent issue
raxod502 commentedon Sep 26, 2017
But it still looks like
electric-indent-modeis broken? I.e. if I pressRETin a Clojure docstring, then point is at column 0 until I pressTABat which point it moves to column 2.bzg commentedon Sep 26, 2017
The behavior I see in a docstring with
clojure-mode version 5.7.0-snapshotis this one:RETgoes at the beginning of the next line, independantly ofelectric-indent-modeC-jindents correctly withelectric-indent-modeturned off, but do the same thanRETotherwiseThe docstring of
C-j(akaelectric-newline-and-maybe-indent) says:So I'm inclined to think
RETandC-jare behaving correctly here, although I too think this is all a bit confusing. I've no good idea right on how to fix this right now.Also beware that
clojure-modedoes not recognize docstring after the function's parameters:raxod502 commentedon Sep 26, 2017
But the docstring for command
newline(bound toRET) says this:So your first bullet point sounds like wrong behavior of
clojure-modeto me, since ifelectric-indent-modeis enabled thenRETshould indent the new line .bzg commentedon Oct 1, 2017
@raxod502 yes, you're right.
#447 is an attempt at fixing the issue at point, please see the PR comment and let me know if this works for you as it works for me.
Thanks!
Fix typos, broken links, and formatting issues in CHANGELOG