Automated length formatting of doc strings

Questions / Help
,
1

We’re currently trying to tighten up standards on an existing code base. One of the current topics is about line length, specifically on the @doc strings. While we use the standard 98, I don’t see any obvious way to anything with the doc strings.

I typically keep doc strings to 80 characters. I find it is much easier to read than anything longer. The problem with hard breaks is if you edit something in the middle, you need tools to rewrap. This would be ideal if it was just part of mix format and, perhaps it is already or could be with a little bit of persuasion and I have no idea how to handle it.

Anyone got tips or automated options outside of mix format?

2

You could write a formatter plugin, that registers itself for sigil: [:m] (or uppercase) and write all the do strings using that.

https://hexdocs.pm/mix/main/Mix.Tasks.Format.html#module-plugins

3

This is only kinda automated, but I’ve installed Rewrap - Visual Studio Marketplace in vscode to do this ad hoc.

4

I would like something like this myself.

I’m a vim user so I’m quite used to typing gqap when I’m done typing in a paragraph. It does mean I leave a blank line above the closing """ to make that smoother—I tell myself it looks nicer :slight_smile: (it actually does, kinda). I follow “first line is a single line short summary” so I never need to rewrap that. So that’s my solution, but it would be nice to have a formatter for it.

PS: agreed re: having the shorter comment length vs code length.

5

That’s what I was looking at, although I was hoping I could have the formatter target doc strings without some kind of sigil magic. I’m completely unfamiliar with writing plugins beyond starting research today.

Thanks! I’ve recently had to transition to VSCode from Sublime and I hadn’t looked into a plugin to handle this.

I had the same issue with whatever Sublime using to rewrap and… I would pop a new line, rewrap, then delete. (If only I was a programmer and figured out a way to automate this, lol.)

As an aside, does Credo support any sort of format/rewrite in its execution? I know Rubocop in Ruby could do some magic for you if you asked it to but I’ve never gotten as familiar with Credo as I was with Rubocop. (I tried a quick Google but I am clearly not asking the right question.)

6

No, but there is styler and recode, which may do this or you can dig into the source to find out how to.

7

Thanks. I have them both flagged to look at now. Having this automated would be amazing.