• Login
Community
  • Login

What is Style: COMMENT DOC KEYWORD ERROR?

Scheduled Pinned Locked Moved Help wanted · · · – – – · · ·
4 Posts 2 Posters 678 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.
  • B
    bunklung
    last edited by Feb 7, 2021, 9:18 PM

    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.

    P 2 Replies Last reply Feb 8, 2021, 12:19 AM Reply Quote 0
    • P
      PeterJones @bunklung
      last edited by Feb 8, 2021, 12:19 AM

      @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
      • P
        PeterJones @bunklung
        last edited by Feb 8, 2021, 12:23 AM

        @bunklung ,

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

        1 Reply Last reply Reply Quote 3
        • B
          bunklung
          last edited by Feb 9, 2021, 12:43 AM

          Thanks for the information! This explains it all now.

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