In our eslint rules we have this:
'multiline-comment-style': ['error', 'separate-lines'],
Which disallow comments such as this:
/* Some
comment */
In favour of this:
// Some
// comment
The problem is that it's possible to ignore this rule by writing the block comments as JSDoc. So this is possible:
/**
* Some
* comment
*/
And we would like to disallow this too. Is there any way to do so, or perhaps some plugin that could be used? All info I can find is how to require JSDoc, but not how to disallow it. Any suggestions?
Related
In a project we our working on we use fairly strict eslint rules for good reason. Occasionally we need to break one of the rules, so we would disable a rule for a specific line. For example:
// eslint-disable-line no-console
In this case we use the eslint-disable-line syntax with the specific rule that we want disabled, to avoid accidentally disabling other rules that are important.
Occasionally a dev will sneak a file in that has // eslint-disable-line without the specific rule, or the dreaded /* eslint-disable */ at the file level.
What I am looking for is a way to force eslint to only accept directives when they include one or more specific rules, so that, for example
// eslint-disable-next-line max-len
would still disable that specific check, but
// eslint-disable-next-line
without the rule would still result in an error.
Plugin eslint-plugin-eslint-comments is what you want.
The closest I got to making eslint-disable stricter is forcing to specify which rules should be disabled using this eslint plugin
So this post is not so much of a "please help me fix it" post as much as it is a "why would changing that make it work?". So I had some javascript/jquery written that was working in firefox and chrome, but IE threw errors.
I could not figure it out even with the helpful posts from users here at stackoverflow. I eventually stumbled upon the answer (as I seem to find myself doing a lot with coding).
I was doing a somewhat rigorous style of commenting taught to me by one of my computer science professors where a function would have commenting such as this:
//# describe function
//# params: param1 - function, param2 - function
//# etc....
So I foolishly threw this into my javascript only to find out that IE really did not care for this much at all. When I removed the # symbols the code worked perfectly.
So my question is why this caused errors in IE? Shouldn't whatever follows the '//' comments not matter?
It does indeed look like some kooky IE conditional comment support. It appears that if # is the first character of a comment (whether it starts with //# or /*#, then IE looks for a conditional comment directive after the # sign. See http://msdn.microsoft.com/en-us/library/8ka90k2e(v=vs.94).aspx for some examples.
AlienWebguy's suggestion should work because the first character of the comment is *. You could probably also just put a space before the # sign:
// # describe function
// # params: param1 - function, param2 - function
// # etc....
You might be thinking of docblock commenting, which you would want to wrap in block comment syntax:
/**
* Function does this
* #param <string> $str The string
* #param <array> $arr The array
* #return <bool> true if string is in array, false if not
*/
I can see IE just being stupid. Odds are even if there is an explanation for why your //# didn't work, it'll likely be a really stupid one, and odds are that only a small percentage of us would even be able to recreate it on our version of IE.
IE is the only browser to my knowledge that looks at conditional comments, so I can see them having a different comment parser than all other browsers which would conflict with otherwise proper code.
I know I can add comments like so:
//This is a comment,
/*so is this*/
But when I do this
/**comment?*/
It has a different color in my text editor (notepad++) and I was wondering whether it has any special meaning, or if it is just a random feature of notepad++.
Here is what it looks like in the text editor:
No, it has not any special meaning. It's more common to use that syntax when documenting code via comments.
The Java language supports three kinds of comments:
/* text /The compiler ignores everything from / to */.
/** documentation /
This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of comment, just like it ignores comments that use / and */. The JDK javadoc tool uses doc comments when preparing automatically generated documentation. For more information on javadoc, see the Java tool documentation.
// text
The compiler ignores everything from // to the end of the line.
Not in JavaScript itself, but some editors will treat it like a JSDoc (https://github.com/jsdoc3/jsdoc) comment to help with autocomplete, etc.
You can also run your code through something like JSDoc to automatically generate HTML documentation for your codebase.
Probably notepad++ identifies it with two different colors just to diversify the type of comment. for a programmer a comment may be more or less important than another :)
might seem like a silly feature, but it is not
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Most of my Javascript functions are relatively simple, and called for their sideeffects: I use jQuery to manipulate the DOM or make Ajax-calls. I prefer to write my functions in the "revealing module pattern" style.
I just discovered that JSDoc- annotating Javascript files has a benefit: with the help of the annotations, Eclipse's JS Development Tools can parse my JS file and fill the Eclipse Outline View (which would otherwise be empty).
Now I wonder what are the fine points, or the good practices of annotating? I am not used to it.
The google JS style guide says something about JSDoc:
recommends to only use a subset of available tags, among other advice.
For now, I came up with this template (this code does not do anything useful):
/**
* #fileOverview Say something meaningful about the js file.
* #author My name
* #version 1.0.1
*/
/**
* #namespace What the namespace contains or which apps/webpages use it
*/
if (!window['my']['namespace']) {
window['my']['namespace'] = {};
my.namespace = (function() {
/**
* Documentation string...
* #memberOf window.my.namespace
* #private
*/
var clear = function(){};
/**
* Documentation string...
* #memberOf window.my.namespace
* #public
*/
function delete_success(data){
var str = "# of files affected: " + data.length;
$('<pre id="success"/>').html(str).appendTo('#del_0b');
$('<pre id="success"/>').html(data.result).appendTo('#del_sf');
}
//more code
return {
"method1": method1,
"delete_success" : delete_success
};
})(); //my.namespace
} //end if
Am I supposed to use JSDoc tag #function or #memberOf here, or both?
What about the #field tag?
Should the return clause be JSDoc'umented as well? With which tags?
Should I really not use the #public tag? I find it useful here.
Any recommendations?
Does anyone know a good, practical JSDoc style guide for small projects?
If you're looking for code samples, I've found that the best place to find them is in the archives of the jsdoc-users Google Group. I've had much better luck there than searching Google, and if you ask a question they're usually pretty good about helping out.
I can't speak for the Eclipse support, but there is a new version of jsdoc, jsdoc3. Check out the documentation here. It's a little incomplete, but I know they have updates written and ready for review, so they should be improving soon.
Regarding your specific question regarding #function and #memberof, you'll likely want to use #function, not #memberof for simple function documentation.
In Eclipse #memberOf (with capital O) does the trick for the outline (Ctrl+O shortcut). I use JSDoc mostly for the Eclipse outline, but I also use #author for humans :)
I also use #private on private functions.
IMHO JSDT is OK but not very helpful, it did not evolve much lately.
You should use an Eclipse JSHint plugin or use TypeScript with an Eclipse plugin (you can do refactoring but adds some complexity).
for me (Eclipse 4.3 Kepler) the following works fine:
my.namespace.foo.AbstractClass = {
/** #memberOf my.namespace.foo.StaticClass <- this statement already
* fixes the Eclipse Outline and Package Views for all other members
*/
staticMethod1 : function() { /* ... */ },
/** no need to add some JSDoc here for the Outline etc. */
staticMethod2 : function() { /* ... */ }
}
(for "non-abstract" classes, speaking Java, it should be similar)
which is nice because:
it's almost the minimum to not repeat the namespace or JSDoc tags all over
I do not have to fiddle around with prototype or this
the "abstract class"1 is immediately created
1: I know - everything is object - but I feel better with stronger typed and namespaced environments/clearer/more defined concepts like in Java. The whole JavaScript stuff is just grown and (IMHO) really bad and hard to work with in bigger environments with multiple programmers and solid refactoring support, good maintainability, testability, modularity, dependency management, self documentation etc.
I'm working in a java/eclipse shop writing javascript, coming from a php/netbeans background. So far, I hate eclipse, but I don't want to shift away from the general tool set. (Because of issues with our build system, we're currently on the galileo release.)
The syntax coloring is just fine, and I'm learning to live with the cockpit-like interface, but eclipse's outliner doesn't properly recognize things like the module pattern at all. Nor does it do much auto-completion on my methods. Can I do anything about that?
I tried installing Aptana, but so far, I haven't noticed any real improvements in basic editing. I see the WTP, which I may or may not have installed. (How do I find out? :) Would that help?
While I'm asking, eclipse does a lousy job with indentation, which I'm constantly having to fix, since I care about such things. Anything to be done about that?
Make sure you have installed JavaScript developer tools. See Help / About Eclipse / WTP (one of the icons at the bottom of dialog) / JavaScript Developer Tools feature
Then on your web project Project / Properties / Project Facets page and make sure JavaScript Toolkit facet is selected. After that you should see JavaScript / Code Style / Formatter page as well as other advanced pages, such as, Libraries, Validation, etc.
Use JSdoc. It will give you back outline and autocomplete! Saved my life the other day...
/**
* #type MyModule
* #memberOf __MyModule
*/
var MyModule = (/** #constructor */ function () {
function innerFunc() {
// blub
}
/**
* #memberOf MyModule
*/
api.publicFunc = function() {
// gak
};
})();
#type MyModule is mandatory and should be the same as your real module name.
#memberOf MyModule and /** #constructor */ at closure function is used to display inner functions and variables inside module closure (i.e. innerFunc()). If you use the same 'type' here as in the #type definition the public functions will be listed in the same outline in Eclipse. Alternatively we can use some other name (here __MyModule and get a separate 'outline tree' for the public methods.
#memberOf module binds the API's methods to your module/type and will make them appear in the outline as well as the auto-complete context-menu (after typing MyModule.| for example).
(Original Idea from http://www.eclipse.org/forums/index.php/m/665434/)