Preserve original indentation in generated documentation

[aj-foster]

Hello 👋🏼

This PR modifies the processing of comments to preserve the original indentation. Here's the methodology:

Most comment sets have a single space at the beginning of each line, ex. // Test. However, there are some situations where all lines may have multiple spaces or no spaces at the beginning. To handle this without disrupting further indents, we look at the minimum number of spaces used for any line that has non-whitespace characters.

Once we trim the minimum number of spaces determined above, all other indentation is preserved. It is no longer necessary to trim while padding the final comments.

You can see the results of these changes in #415.

Would love your feedback ❤️

[whatyouhide]

The change looks great, but can we add a test for it?

[whatyouhide]

To do a single pass on the list, use Enum.min_by/3 instead of these three passes on the list.

Suggested change

	|> Enum.reject(&String.match?(&1, ~r/^\s*$/))
	|> Enum.map(fn line ->
	Regex.run(~r/^\s*/, line, capture: :first)
	|> List.first()
	|> String.length()
	end)
	|> Enum.min(fn -> 0 end)
	Enum.min_by(split_comments, fn line ->
	if line =~ ~r/^\s*$/ do
	0
	else
	~r/^\s*/
	|> Regex.run(line, capture: :first)
	|> List.first()
	|> String.length()
	end
	end)

[aj-foster]

I had to work on this a bit more. 647c726 replaces this phrase with an Enum.reduce because we need the following properties:

1. Empty (or whitespace-only) lines should not affect the minimum
2. We want to end up with a number, rather than the original line.

The reduce leans on the global sort order (:unset is greater than any integer) which may not be the most clear. Another option would be to use a tagged accumulator. What do you think?

[v0idpwn]

Tried turning this into a single regex expression:

    case Regex.run(~r/^(\s+)(?=\S)/, line, capture: :first) do
      [first] -> String.length(first)
      _ -> 0
    end

Should be equivalent and a bit faster

[aj-foster]

@v0idpwn is that based on the suggestion above, or the changes in 647c726? As mentioned above, we don't want empty (or whitespace-only) lines to force a minimum of 0.

[whatyouhide]

@aj-foster the comment from @v0idpwn still applies, you can use a single regex run instead of the if.

[aj-foster]

Made this change in 14bdbed. 👍🏼

[aj-foster]

Thanks @whatyouhide. I adapted an existing docs-related test in order to avoid messing with another message in the test proto. Resolved the feedback items, but did have to go a different route for one of them (commented above).