Skip to content

Identation issues in docstrings #241

Closed

Description

@expez
(ns test.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.")

Activity

  1. bbatsov commented on Jul 18, 2014

    @bbatsov
    Member

    @bzg is working on this particular feature.

  2. bzg commented on Jul 19, 2014

    @bzg
    Contributor

    Thanks for the heads up.

    I'll have a look but can't do it before next week.

  3. bbatsov commented on Jul 21, 2014

    @bbatsov
    Member

    @bzg No worries. Now that we have some unit tests you might add a few for the docstring filling logic as well.

  4. expez commented on Jul 21, 2014

    @expez
    MemberAuthor

    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:

    (defn foo []
      "Alignment
       like this")
    
    (defn bar []
      "Instead
      of this")

    This would make it consistent with how the content of a [ ] is indented. E.g. we do this:

    (let [foo (bar)
          baz (atom nil)]
    ...)

    and not this, where baz is aligned with [ and not foo:

    (let [foo (bar)
         baz (atom nil)]
    ...)

    Thoughts?

  5. bzg commented on Jul 26, 2014

    @bzg
    Contributor

    @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?

  6. expez commented on Jul 26, 2014

    @expez
    MemberAuthor

    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.

  7. arrdem commented on Jul 26, 2014

    @arrdem
    Contributor

    @expez the problem with this example you present...

    (defn foo []
      "Alignment
       like this")
    
    (defn bar []
      "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

    (defn f
      "(λ x) → ⊤
       (λ x → y) → ⊤"
      ([x])
      ([x y]))

    which exhibits exactly this mis-alignment behavior.

    user> (defn f
      "(λ x) → ⊤
       (λ x → y) → ⊤"
      ([x])
      ([x y]))
    
    #'user/f
    user> (use 'clojure.repl)
    nil
    user> (doc f)
    -------------------------
    user/f
    ([x] [x y])
      (λ x) → ⊤
       (λ x → y) → ⊤
    nil

    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.

  8. bzg commented on Jul 27, 2014

    @bzg
    Contributor

    I created this PR (#244) which adds an option for this.

  9. expez commented on Jul 27, 2014

    @expez
    MemberAuthor

    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 :)

  10. bbatsov commented on Jul 27, 2014

    @bbatsov
    Member

    @arrdem I guess we should simply patch doc to handle both styles. The existing default seems pretty odd to me.

  11. arrdem commented on Jul 28, 2014

    @arrdem
    Contributor

    @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 👅

  12. genovese commented on Dec 5, 2014

    @genovese

    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)
    
  13. bzg commented on Dec 5, 2014

    @bzg
    Contributor

    Hi Christopher,

    Christopher Genovese notifications@github.com writes:

    I am having a persistent but somewhat different problem with
    docstring indentation.

    Sorry, I won't have time to check this particular issue before long, I hope someone else will.

  14. genovese commented on Dec 5, 2014

    @genovese

    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 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.

  15. 6 remaining items

  16. bzg commented on Jan 27, 2015

    @bzg
    Contributor

    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.

  17. stig commented on Jun 10, 2015

    @stig

    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.)

  18. added a commit that references this issue on Jun 14, 2015
  19. sandhu commented on Jun 15, 2015

    @sandhu
    Contributor

    The #289 PR that got merged this weekend should address this issue.

  20. tsdh commented on Jun 15, 2015

    @tsdh
    Contributor

    Great, thanks!

  21. stig commented on Jun 16, 2015

    @stig

    Hurrah!

  22. added a commit that references this issue on May 6, 2016
  23. raxod502 commented on Sep 26, 2017

    @raxod502

    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.

  24. bzg commented on Sep 26, 2017

    @bzg
    Contributor

    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)
    
  25. raxod502 commented on Sep 26, 2017

    @raxod502

    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 .

  26. bzg commented on Oct 1, 2017

    @bzg
    Contributor

    @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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions