Crystal: Documentation empty line rule is a pain

[trans]

Reading about best practices for documenting code, I find:

# A unicorn is a **legendary animal** (see the `Legendary` module) that has been
# described since antiquity as a beast with a large, spiraling horn projecting
# from its forehead.
class Unicorn
end

# Bad: This is not attached to any class.

class Legendary
end

Problem is, I am porting a bunch of Ruby code for a particular project, and it really sucks to have go through it all just to make sure there are no empty lines there, and on all the methods too. Moreover, some people actually just prefer that style. In fact in my experience, people who do, tend to write cleaner code. I don't know why, but it often seems to be the case. Myself I am a bit of a waffler. On some projects I have and some I haven't. In any case, it's just a waste of programmer's time to make such a restriction.

Can the rule be changed so if there are _two empty lines_ then it won't apply?

[asterite]

But what if you want to put some comment between two declarations without that comment appearing in the docs? That's why the rule exists.

[trans]

Option 1: Extra line (very easy)

# No show.


class Foo
   ...
end

Option 2: Add actual comment. It can be empty, but it probably shouldn't be anyway.

# No show. 

#
class Foo
  ...
end

Option 3: Does the doc tool have some type of hiding marker? Example might be,

#/
# No show.
#\
class Foo
  ...
end

Another possibility in the future, if Crystal's doc tool supports tags, something like @internal might be of use too.

# @internal No show. 
class Foo
  ...
end

reference: https://groups.google.com/forum/#!topic/yardoc/xOIfLTzLbB8

[RX14]

I think the current rule makes more visual and syntactic sense than either of the proposed alternatives. Parity with ruby isn't a good enough rule to change this, especially considering you're likely to have to rewrite all the doc formatting anyway because thats not particularly compatible either.

[samueleaton]

I think, even better, would be support for multiline comments, which would make things nicer for documenting.

#=
Foo is a really cool guy.

You gotta be careful with Foo. If you're not careful, he'll get ya'.

I can put as much space in this comment as I dang feel like.


see?

=#
class Foo
  ...
end

[trans]

@RX14 If there wasn't an aspect of personal preference involved in this I would say you are right. But there is. So why should there be such a huge limitation, in order to support something that hardly ever happens -- how often do you really add comments that you don't want to show up in docs, in a place where they would otherwise show up?

[trans]

@samueleaton So you think Crystal should have a block comment form? Ironically even languages that do (e.g. /* ... */) tend to run *s all the way down. So maybe there is a reason not too do this -- i.e. a large code example might get mistaken for actual code? I guess that was the original reason for it. But with modern editors, is it really a problem anymore? I could go either way on this, I guess.

[samueleaton]

@trans Documentation is only only area where I'm really missing multiline comments. Its _super_ convenient to not have to think about doing comments and just be able to do markdown. And if I've learned anything from studying UX convenience = more documentation (in this case).

I see what you're saying about about mistaking something for code, but for 99.9% of users an editor should be graying that out.

[RX14]

@trans I've made misc implementation comments in the root of classes that shouldn't be in the API docs many time. For example: https://github.com/RX14/multipart.cr/blob/master/src/http/multipart/generator.cr#L27

[trans]

@RX14 But that wouldn't have caused a problem b/c content_type is documented.

[asterite]

Closing. Doc comments must be attached to declarations.