sponsor Vim development Vim logo Vim Book Ad

jcommenter.vim : A script for automatically generating JavaDoc comments

 script karma  Rating 368/165, Downloaded by 11444  Comments, bugs, improvements  Vim wiki

created by
Kalle Björklid
 
script type
utility
 
description
Updated 29.12.2002 KB

Description:
Generates JavaDoc (and some other) comments for java-sources. This is triggered by executing the JCommentWriter()-function while the cursor is over something meaningfull, or if a selection exists, the selected text is parsed and the comment template is generated based on that.

The following comments are generated (in the appropriate situations):
1. File comments: user specifies the template, generated when the cursor is on the first line of the file.
2. Class comments: generated when on top of a class declaration
3. Method comments: generated when on top of a metod declaration. @return, @params, and @throws are generated, if applicable. If executed on a method declaration which already has JavaDoc-comments, updates the javadoc-comments by removing/adding tags as needed.
4.  Field comments. Simply adds an empty JavaDoc-comment template above the field declaration
5. Copy @<name> -tags. When executed on @something, creates a tag with the same name directly above the line the cursor is currently on.
6. @throws for RuntimeExceptions. When executed on a line containing something like "throw new RuntimeException()", a @throws-tag is added to the previous JavaDoc-comment.
7. Block-end comments. When executed on a line containing a '}'-character and possibly some whitespace (but nothing else), generates a one-line-comment describing what block the '}' is terminating. For example, the comment for "aVeryLongMethod" is  "// END: aVeryLongMethod".

There are a bunch of other functions to support the comment generation (see the start of the script for full documentation). The style of the comment templates is configurable (see the file for configuration and description of the options)
 
install details
Add the jcommenter.vim to your macros-folder (or whatever).
Here's what I have in my .vimrc:

  autocmd FileType java let b:jcommenter_class_author='Kalle Björklid (bjorklid@st.jyu.fi)'
  autocmd FileType java let b:jcommenter_file_author='Kalle Björklid (bjorklid@st.jyu.fi)'
  autocmd FileType java source $VIM/macros/jcommenter.vim
  autocmd FileType java map <M-c> :call JCommentWriter()<CR>

So I use Alt-c for commenting the file/methods/attributes/classes.
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
jcommenter.vim 1.3.1 2002-12-29 6.0 Kalle Björklid Fixed two bugs concerning the modifications for 1.3
jcommenter.vim 1.3 2002-12-29 6.0 Kalle Björklid Added check to see whether the script is already loaded
Option to have an empty line automatically added before the generated comment if there was none previously. See config ("b:jcommenter_add_empty_line").
jcommenter.vim 1.2.1 2001-11-25 6.0 Kalle Björklid Added support for generating modelines.
User requests:
Added possibility to have default tag values.
Added possibility to have space between tag groups.
jcommenter.vim 1.2 2001-10-24 6.0 Kalle Björklid A bunch of new features (some seem to be actually useful ;-) :
Complete method comment updating: now adds/removes @return- and @param-tags form existing doc comments if no more applicable.
Added a new public function (+ mappings for it) for searching incomplete doc-comments (This is nice - a quick way to complete comments and to jump to next incomplete comment)
If executed on a line like "throw new RuntimeExeception()" will add an exception declaration to prev. javadoc comments.
Corrected a problem where updating didn't work if a new parameter's name began the same way than an existing one's.
Now behaves correctly when "extra stuff" (after the '{') is included in the range.
Added mapping for insert-mode to config-file.
Added an abbreviation (see config-file)
Now adds the method/class/if/while/for... name as an ending comment when executed on a line containing only whitespace and a '}'.
Comment generation can now be virtually fully automated by using an abbreviation for '{' (which is presented in the config-file).
jcommenter.vim 1.12 2001-10-16 6.0 Kalle Björklid Fixed a problem which caused all methods to be interperted as constructors (no @return-tag generated).
jcommenter.vim 1.11 2001-08-14 6.0 Kalle Björklid Fixed an error concerning the removal of the return tag when updating the comments (the buffer was partially deleted from the line where the @return tag was to EOF)
jcommenter.vim 1.1 2001-08-12 6.0 Kalle Björklid This is again a .vim file (and not a zip). The configuration file is pasted at the beginning of the script. Again, see the script
for instructions.

Can now choose between '@throws' and '@exception' tags.
When executed on single-line comments ("/** blah blah */") expands them into multiline comments preserving the text
Partial method documentation comment updating (adds tags instead of writing a new template)
jcommenter.vim 1.0 2001-08-11 6.0 Kalle Björklid A note:
since there was two files in this version of the script, I zipped them. However, if you download the file, it has .vim-extension, so you have to rename it.
I'm really sorry for the inconvience.
jcommenter.vim 1.0 2001-08-11 6.0 Kalle Björklid Did a complete rewrite of the script-code (this is the main reason for the version-number leap).
A separate config-file, which should be modified to reflect the user's preferences.
More variables for better customization.
Due to the rewrite, should now be more robust
Cursor movement and auto-start insert mode
Better control over the look of the comment templates

Read new installation and configuration instructions from the .vim files
jcommenter.vim 0.41 2001-07-15 5.7 Kalle Björklid Fixed the problem with final method parameters.
jcommenter.vim 0.4 2001-07-06 5.7 Kalle Björklid Recognizes now methods that have whitespaces just before the '('.
The file comments can now be completely redefined without editing the script.
The comment-skeleton for fields is changed to correspond with the Sun's code conventions.
jcommenter.vim 0.3 2001-06-17 5.7 Kalle Björklid - Recognices interfaces (same as classes)
- improved recognition for methods/attributes
- Added tag copying:
   For example, when executed on the following line:
      * @throws IOException If cannot read file
   the result is:
      * @throws IOException If cannot read file
      * @throws
   Not that life changing, but quite nice when you want to document those
   RuntimeExceptions, or need to add another paramter.
jcommenter.vim 0.2 beta 2001-06-13 5.7 Kalle Björklid Initial upload
ip used for rating: 54.157.61.194

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
Vim at Github