Stricter rules for comments

[raduserbanescu]

As per the documentation on comments (sections 18.2 & 18.3) I think stricter rules can be enforced. Below is something I have tested in my projects.

-    'line-comment-position': ['off', {
+    'line-comment-position': ['error', {
       position: 'above',
       ignorePattern: '',
       applyDefaultPatterns: true,
     }],

-    'no-inline-comments': 'off',
+    'no-inline-comments': 'error',

     'spaced-comment': ['error', 'always', {
       line: {
         exceptions: ['-', '+'],
-        markers: ['=', '!'], // space here to support sprockets directives
+        markers: ['=', '!', '/'], // space here to support sprockets directives
       },
       block: {
         exceptions: ['-', '+'],
         markers: ['=', '!'], // space here to support sprockets directives
-        balanced: false,
+        balanced: true,
       }
     }],

The / marker is commonly used by some libraries (ex: angular-gettext) to denote documentation.

/// Special comment

[ljharb]

They indeed can be; we've intentionally chosen not to, as there doesn't seem to be much value in legislating comments in this way. Since comments should never describe "what" (should never be documentation), only "why" or history/motivation, this just doesn't come up much in practice.

[raduserbanescu]

Ok, I understand your reasons. I only thought that since they were in the documentation, they could also be in the lint configuration. I will still use them in my projects where it will make sense.

One more question if I may. As per section 18.1 I know you use /** ... */ for multi-line comments and from this issue comment I see you do not encourage JSDoc.

But isn't this a JSDoc style comment? (possible problems for the JSDoc parser?)

/**
 * Multiple
 * lines
 * comment
 */

...instead of the common C style comment (although I find that it does't look as good)

/*
 * Multiple
 * lines
 * comment
 */

[ljharb]

Generally I'd say you're absolutely right! For line-comment-position, we've configured it properly, we just haven't enabled it; I'd love a PR that fixed the configuration in spaced-comment though.

It's a JSDoc-style comment if it's following the conventions for jsdoc; certainly if a jsdoc parser would break on it, it's not jsdoc-style.

I don't think there's a particularly strong reason to start multiline comments with /**, but I also don't think there's a strong reason not to. Since we disallow JSDoc, JSDoc's conventions don't exist for us :-)

[raduserbanescu]

I will make a PR just for the spaced-comment option. Should I also include the extra / marker?

Thank you for your clarification regarding /** ... */ multi-line comments.

I will do it next week as I am on the road at the moment.

[ljharb]

I don't see much value in supporting the extra / marker, but the rest seems good.