What is Style: COMMENT DOC KEYWORD ERROR?

bunklung

I am trying to figure out how to configure COMMENT DOC KEYWORD and COMMENT DOC KEYWORD ERROR, but it’s not clear what the syntax is so that Notepad++ will do the highlighting.

Can someone explain this style and how to trigger the highlighting?

Thanks.

PeterJones

@bunklung ,

Each language’s lexer defines its own list of styles, so you’d have to know the individual programming language.

When I look at the source code for the C++ lexer, I see that the comment-doc-keyword starts when it sees a * @ (I presume in a comment, though I didn’t check the full logic), followed by alphanumerics.

The comments mentinoed “JavaDoc” and “Doxygen”, and searching for “JavaDoc” “comment doc” found me this page, which gave some example text. With that and the mention of “Doxygen”, I was reminded that “comment doc keywords” are ways to markup your comments in a standard format, so that you can run a converter to parse the comments in your source code and then automatically generate other help files external to the source code.

I changed my settings so they were obvious (yellow for good, red for bad)

,

then pasted in the example text from the JavaDoc page above. I then experimented until I created an error:

/**
* Returns an Image object that can then be painted on the screen. 
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument. 
* <p>
* This method always returns immediately, whether or not the 
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives 
* that draw the image will incrementally paint on the screen. 
*
* @param  url  an absolute URL giving the base location of the image
* @param  name the location of the image, relative to the url argument
* @return      the image at the specified URL
* @see         Image
* @blah   x 
*/

yields

So @param and @return describe the contents of function parameter variables and function return calls, but JavaDoc doesn’t know what @blah is supposed to document, so it marks it as an error.

So that was a long answer with an example in one language. It may be that different language lexers implement different standards for the COMMENT DOC KEYWORD syntax, or it may be that they all implement the same; I didn’t scour all builtin lexers’ sourcecode to find out. But basically, if you are using one of the comment-to-documentation standards that your language’s lexer supports, it will highlight those comment statements according to the rules that the lexer defines.

PeterJones

@bunklung ,

PS: the Doxygen wikipedia page gives examples in that documentation generator’s style, too.

bunklung

Thanks for the information! This explains it all now.