Defining and Formatting Comments in Vim

and a space for you. Now you can type the comment text. When it gets longer than 'textwidth', Vim will break the line. Again, the star is inserted automatically: >c /* * This is a test of the text formatting. * Typing a lot of text here will make Vim * break */ For this to work some flags must be present in 'formatoptions': r insert the star when typing <Enter> in Insert mode o insert the star when using "o" or "O" in Normal mode c break comment text according to 'textwidth' See |fo-table| for more flags. DEFINING A COMMENT The 'comments' option defines what a comment looks like. Vim distinguishes between a single-line comment and a comment that has a different start, end and middle part. Many single-line comments start with a specific character. In C++ // is used, in Makefiles #, in Vim scripts ". For example, to make Vim understand C++ comments: > :set comments=:// The colon separates the flags of an item from the text by which the comment is recognized. The general form of an item in 'comments' is: {flags}:{text} The {flags} part can be empty, as in this case. Several of these items can be concatenated, separated by commas. This allows recognizing different types of comments at the same time. For example, let's edit an e-mail message. When replying, the text that others wrote is preceded with ">" and "!" characters. This command would work: > :set comments=n:>,n:! There are two items, one for comments starting with ">" and one for comments that start with "!". Both use the flag "n". This means that these comments nest. Thus a line starting with ">" may have another comment after the ">". This allows formatting a message like this: > ! Did you see that site? ~ > ! It looks really great. ~ > I don't like it. The ~ > colors are terrible. ~ What is the URL of that ~ site? ~ Try setting 'textwidth' to a different value, e.g., 80, and format the text by Visually selecting it and typing "gq". The result is: > ! Did you see that site? It looks really great. ~ > I don't like it. The colors are terrible. ~ What is the URL of that site? ~ You will notice that Vim did not move text from one type of comment to another. The "I" in the second line would have fit at the end of the first line, but since that line starts with "> !" and the second line with ">", Vim knows that this is a different kind of comment. A THREE PART COMMENT A C comment starts with "/*", has "*" in the middle and "*/" at the end. The entry in 'comments' for this looks like this: > :set comments=s1:/*,mb:*,ex:*/ The start is defined with "s1:/*". The "s" indicates the start of a three-piece comment. The colon separates the flags from the text by which the comment is recognized: "/*". There is one flag: "1". This tells Vim that the middle part has an offset of one space. The middle part "mb:*" starts with "m", which indicates it is a middle part. The "b" flag means that a blank must follow the text. Otherwise Vim would consider text like "*pointer" also to be the middle of a comment. The end part "ex:*/" has the "e" for identification. The "x" flag has a special meaning. It means that after Vim automatically inserted a star, typing / will remove the extra space. For more details see |format-comments|. ============================================================================== Next chapter: |usr_31.txt| Exploiting the GUI Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl:

This section details defining comments in Vim using the 'comments' option, differentiating between single-line and multi-part comments. It explains how to specify comment starts, middles, and ends with flags like 's', 'm', and 'e', and how flags like 'n', 'b', and 'x' affect nesting, spacing, and automatic formatting. The section illustrates formatting email replies with '>' and '!' characters and demonstrates setting comments for C-style comments using '/*', '*', and '*/'.