Community
    • Login

    What is Style: COMMENT DOC KEYWORD ERROR?

    Scheduled Pinned Locked Moved Help wanted · · · – – – · · ·
    4 Posts 2 Posters 674 Views
    Loading More Posts
    • Oldest to Newest
    • Newest to Oldest
    • Most Votes
    Reply
    • Reply as topic
    Log in to reply
    This topic has been deleted. Only users with topic management privileges can see it.
    • bunklungB
      bunklung
      last edited by

      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.

      PeterJonesP 2 Replies Last reply Reply Quote 0
      • PeterJonesP
        PeterJones @bunklung
        last edited by

        @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)
        4fa68066-a8cd-494d-9eea-45b63b61a36d-image.png
        ab2dec78-3da8-4cf4-8cf7-155953839188-image.png ,

        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
        a1f78fbd-9ad6-4497-93f7-451f34fa7bc9-image.png

        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.

        1 Reply Last reply Reply Quote 5
        • PeterJonesP
          PeterJones @bunklung
          last edited by

          @bunklung ,

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

          1 Reply Last reply Reply Quote 3
          • bunklungB
            bunklung
            last edited by

            Thanks for the information! This explains it all now.

            1 Reply Last reply Reply Quote 2
            • First post
              Last post
            The Community of users of the Notepad++ text editor.
            Powered by NodeBB | Contributors