Loading ...
Sorry, an error occurred while loading the content.

Question about DocComments in PHP (perhaps other languages as wel...)

Expand Messages
  • Christ van Willegen
    Hi, I ran into a problem yesterday when an annotation in a doc comment was not picked up by a comment handler. Long story short: It turned out that I had typed
    Message 1 of 2 , Oct 1, 2011
    View Source
    • 0 Attachment
      Hi,

      I ran into a problem yesterday when an annotation in a doc comment was
      not picked up by a comment handler. Long story short: It turned out
      that I had typed /* where I should have typed /** to open the
      comment.

      For Vim, this is all comment, so it wasn't immediately noticeable.

      I would like to add a request for the php.syntax (and perhaps others
      as well?) to:

      *) Include a 'DocComment' type (opened with /** or perhaps /*!) so
      that it could be colored differently, and/or

      *) check for annotations in comments (annotations usually start with
      an @, after a space, so ' @' would start an annotation) and highlight
      them as warnings

      I can provide examples if they are wanted/needed.

      Thanks in advance for any insights or help!

      Christ van Willegen
      --
      09 F9 11 02 9D 74 E3 5B D8 41 56 C5 63 56 88 C0

      --
      You received this message from the "vim_dev" maillist.
      Do not top-post! Type your reply below the text you are replying to.
      For more information, visit http://www.vim.org/maillist.php
    • Benjamin R. Haskell
      ... The following seems to work okay for PHP. I m not sure there s a reliable way to do this more generically, since various {language}Doc comment styles have
      Message 2 of 2 , Oct 3, 2011
      View Source
      • 0 Attachment
        On Sat, 1 Oct 2011, Christ van Willegen wrote:

        > Hi,
        >
        > I ran into a problem yesterday when an annotation in a doc comment was
        > not picked up by a comment handler. Long story short: It turned out
        > that I had typed /* where I should have typed /** to open the
        > comment.
        >
        > For Vim, this is all comment, so it wasn't immediately noticeable.
        >
        > I would like to add a request for the php.syntax (and perhaps others
        > as well?) to:
        >
        > *) Include a 'DocComment' type (opened with /** or perhaps /*!) so
        > that it could be colored differently, and/or
        >
        > *) check for annotations in comments (annotations usually start with
        > an @, after a space, so ' @' would start an annotation) and highlight
        > them as warnings
        >
        > I can provide examples if they are wanted/needed.

        The following seems to work okay for PHP. I'm not sure there's a
        reliable way to do this more generically, since various {language}Doc
        comment styles have various extensions that vary across languages.
        (E.g. some langs take a more XML-y approach to it.)

        Regardless... see my ~/.vim/after/syntax/php.vim below. Some notes:

        I split phpComment into phpComment and phpMultiLineComment. Probably
        excessive, but I had to redefine the phpMultiLineComment stuff to get
        folding working at some point in the past, and it seemed cleaner (?).

        The file below handles "shared" PHPdoc blocks:

        /**#@+ aaa */
        ...
        /**#@-*/

        (where 'aaa' is PHPdoc to be applied to all PHPdoc blocks within '...').

        One thing it does improperly (though I can't tell why) is indentation
        for the following:

        /* Normal
        * comment
        */

        If you hit 'o' on the line with 'Normal' in it, the '*' is outdented.
        If you hit 'A' on that line, then hit <Enter>, it's fine.

        Either way, hopefully useful. I know it has been for me.

        --
        Best,
        Ben


        sil! syn clear phpComment

        syn region phpDocCommentShared matchgroup=phpDocCommentSharedTag start=~/\*\*#@+\_.\{-}\*/~ end=~/\*\*#@-\*/~ contains=@phpClTop containedin=phpRegion transparent fold

        syn region phpDocComment start=+/\*\*\(#@[+\-]\)\@!+ end=+\*/+ contained containedin=phpRegion contains=phpTodo,phpDocTag fold

        syn region phpMultiLineComment start=+/\*\*\@!+ end=+\*/+ contained containedin=phpRegion contains=phpTodo fold
        syn match phpMultiLineComment +/\*\*/+ contained containedin=phpRegion

        syn match phpComment /#.\{-}\(?>\|$\)\@=/ contained contains=phpTodo
        syn match phpComment +//.\{-}\(?>\|$\)\@=+ contained contains=phpTodo

        syn match phpDocTag /\ \@<=@\w\+/ contained

        syn cluster phpClTop add=phpDocComment,phpDocCommentShared,phpMultiLineComment

        hi def link phpDocComment Special
        hi def link phpMultiLineComment Comment
        hi def link phpDocTag Keyword
        hi def link phpDocCommentSharedTag Identifier

        --
        You received this message from the "vim_dev" maillist.
        Do not top-post! Type your reply below the text you are replying to.
        For more information, visit http://www.vim.org/maillist.php
      Your message has been successfully submitted and would be delivered to recipients shortly.