Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[lib] How to format sectioning comments in synopsis #802

Closed
tkoeppe opened this issue Jul 7, 2016 · 7 comments
Closed

[lib] How to format sectioning comments in synopsis #802

tkoeppe opened this issue Jul 7, 2016 · 7 comments

Comments

@tkoeppe
Copy link
Contributor

tkoeppe commented Jul 7, 2016

Comments in a synopsis that refer to sections come in a variety of styles at the moment:

// 34.8, Capital letters

// 34.8, lowercase like this

// 34.8, lowercase with colon:

// See 34.8, something something

We should probably agree on a style. I think the third one is the most prevalent (lowercase with colon), though the second one is also widely used, and @zygoloid doesn't think the colon is helping any.

@burblebee
Copy link
Contributor

I've been using the 3rd one (lowercase with colon), because as you noted, it is the most prevalent.

@zygoloid
Copy link
Member

I think we should be choosing between the second and third options. My preference is the second form, because the colon seems like noise to me (and I like the contents of the line after the comma to match the section name), but if consensus among editors is that the third is better, that's fine with me.

@burblebee
Copy link
Contributor

On Sun, Jul 10, 2016 at 05:18:50PM -0700, Richard Smith wrote:

I think we should be choosing between the second and third options. My preference is the second form, because the colon seems like noise to me (and I like the contents of the line after the comma to match the section name), but if consensus among editors is that the third is better, that's fine with me.

I've been using the 3rd option because that's the most common one.
It would be good to be consistant in any case.

@burblebee
Copy link
Contributor

On Fri, Nov 18, 2016 at 11:17:02AM -0800, dawn@burble.org wrote:

On Sun, Jul 10, 2016 at 05:18:50PM -0700, Richard Smith wrote:

I think we should be choosing between the second and third options. My preference is the second form, because the colon seems like noise to me (and I like the contents of the line after the comma to match the section name), but if consensus among editors is that the third is better, that's fine with me.

I've been using the 3rd option because that's the most common one.
It would be good to be consistent in any case.

I should add, that I really don't have a preference between 2 and 3, as
long as we're consistent.

@tkoeppe
Copy link
Contributor Author

tkoeppe commented Nov 18, 2016

I should add, that I really don't have a preference between 2 and 3, as
long as we're consistent.

Same here. Option 3 seems like the most prevalent one, so simplicity suggests we stick with that, but I'm also just as happy with 2 as with 3 in principle.

@jensmaurer jensmaurer changed the title How to format sectioning comments in synopsis [lib] How to format sectioning comments in synopsis Nov 21, 2016
@jensmaurer
Copy link
Member

I second @zygoloid here, the colon is adding nothing.

@jwakely
Copy link
Member

jwakely commented Nov 21, 2016

I find the colon unnecessary too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants