It looks like mix format doesn’t format documentation, for example a very long line is not splitted over a new line. Is this a bug, or is documentation formating out of scope for format?
Thanks.
Documentation are strings, wrapping those strings would change the AST.
Consider "foo bar" beeing to long, after it has been split it becomes `“foo\nbar”, which is a different string and therefore has a different representation in the AST.
You’ll need to wrap your documentation using another tool or manually.
It is currently out of scope. I saw some discussion on the subject, however, so maybe in future it’ll do it. At the moment it’s not supported.
IMHO mix format should not change the content of your documentation as they are just strings, if you really want to have formatted examples, you could use a simple macro like this and then mix format would format the code inside the interpolation.
I think I agree for the most part, but some thing like automatic indentation and line lengths are things that could be handled by the formatter I guess?
Do you have a code snippet we can look at? Maybe show what you have now and how you’d prefer the formatter to format it.
The formatter is dumb, it does not know if the string it sees is ordinary code or documentation. Changing it in any way might result in broken output if it is regular code, therefore string literals are not touched.
While that’s true, it can become smarter. ex_doc does parse those comment strings and understands that this is code example.
ExDoc is not the formatter, nor is it part of it.
1 Like
It’s really simple actually:
@doc """
This is a very long explanation of a function that is longer than the default length of 98 characters and so I would have expected it to be split on different lines like the same sentence below this one.
This is a very long explanation of a function that is longer than the default length of 98 characters and
so I would have expected it to be split on different lines like this example.
"""
def foo(), do: nil
The AST of those are different though, which the formatter absolutely, positively, should NOT ever change:
iex> a1 = quote do """
This is a very long explanation of a function that is longer than the default length of 98 characters and so I would have expected it to be split on different lines like the same sentence below this one.
""" end
"This is a very long explanation of a function that is longer than the default length of 98 characters and so I would have expected it to be split on different lines like the same sentence below this one."
iex> a2 = quote do """
This is a very long explanation of a function that is longer than the default length of 98 characters and
so I would have expected it to be split on different lines like this example.
""" end
"This is a very long explanation of a function that is longer than the default length of 98 characters and \nso I would have expected it to be split on different lines like the same sentence below this one."
iex> a1 == a2
false
Not only is the AST different, the string itself is different! A formatter should not change user specified strings! It could easily break things, say like documentation, or an embedded macro language. I’d argue it’s the job of the IDE to wrap long strings visually.
3 Likes
