sponsor Vim development Vim logo Vim Book Ad

scalacommenter.vim : Functions for documenting Scala-code

 script karma  Rating 8/2, Downloaded by 1521    Comments, bugs, improvements  Vim wiki

created by
richard emberson
script type
Re-written using the Self.vim Object prototype system, hence
justifying a major version number increase
(see: http://www.vim.org/scripts/script.php?script_id=3072).
The self.vim code is embedded in the scalacommenter.vim code
so you don't need to download self.vim.

Inspired by Kalle Bjorklid's JCommenter.
Works on Vim version 7.0 and above

This has two capabilities:
  1) Generating a comment template, and
  2) Formatting an existing set of comment tags.

Generating ScalaDoc comments for Scala sources.
This is triggered by executing the ScalaCommentWriter() function
  1) while the cursor is over something meaningful, or
  2) if a (visual) selection exists,
The selected text is parsed and the comment template generated.

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
    Tags if applicable: @author, @version, @since, @param, @tparam and @throws
3. Trait comments: generated when on top of a trait declaration
    Tags if applicable: @author, @version and @since
4. Object comments: generated when on top of a object declaration
    Tags if applicable: @author, @version and @since
5. Inner Class comments: generated when on top of an inner class declaration
    Tags if applicable: @param, @tparam and @throws
6. Inner Trait comments: generated when on top of an inner trait declaration
7. Inner Object comments: generated when on top of an inner object declaration
8. Method comments: generated when on top of a method declaration.
    Tags if applicable: @param, @tparam, @return and @throws
9. Fields, val and var, comments: generated when on top of a var or val

If executed and the class, trait, object or method already has a ScalaDoc
comment, an attempt is made to add/remove parameter and template parameter
tags as needed.

Formatting existing ScalaDoc comments for Scala sources.
This is triggered by executing the ScalaCommentFormatter() function
The user (visual) selection of the comment tag lines to be formatted
and invokes the ScalaCommentFormatter() function.
As an example, the following is selected and formatted:
   * @author    Tom  Jones
   * @version   1.3 03/10/50
   * @param  name This is the name
   * @param  value the value to associate with the value
   *  This is a second line. Here is a second second line.
   *    This is a third line. Here is a third third line.
   * @throws java.io.EOFException For no reason
   * @author Jane Doe
   * @author  Tom Jones
   * @author  Jane Doe
   * @version 1.3 03/10/50
   * @param   name                         This is the name
   * @param   value                          the value to associate with the value This
   *                                                     is a second line. Here is a second second
   *                                                     line. This is a third line. Here is a third
   *                                                     third line.
   * @throws  java.io.EOFException For no reason

Note that tags are re-ordered and grouped based upon Sun's JavaDoc guide.
The start line selected to be formatted must be a comment tag line.
The end line selected to be formated should be a comment tag line
or a line containing additional text for a previous tag line.

Work flow:
  Generate comment template,
  Fill in template and then
  Format the comment's tags.

For more details about what is produced and how to configure the production,
see the start of the script for additional documentation.

Source can be found at: https://github.com/megaannum/scala_commenter

install details
Add the scalacommenter.vim to your .vim directory (or whatever).
Here's what I have in my .vimrc:

  autocmd FileType scala source $HOME/.vim/scalacommenter.vim
  autocmd FileType scala map <M-c> :call ScalaCommentWriter()<CR>
  autocmd FileType scala map <M-f> :call ScalaCommentFormatter()<CR>
  autocmd FileType scala map cm :call ScalaCommentWriter()<CR>
  autocmd FileType scala map cf :call ScalaCommentFormatter()<CR>
  autocmd FileType scala let b:scommenter_class_author='Richard Emberson'
  autocmd FileType scala let b:scommenter_file_author='Richard Emberson'
  autocmd FileType scala let g:scommenter_file_copyright_list = [
  \    'COPYRIGHT',
  \    'Second line of copyright',
  \    'And a third line'
  autocmd FileType scala let b:scommenter_extra_line_text_offset = 20
  autocmd FileType scala let b:scommenter_user_tags = [
  \["pre", 0, 1, 0],
  \["post", 0, 1, 0],
  \["requires", 1, 1, 0],
  \["provides", 0, 1, 0]

The user tags: "pre", "post", "requires" and "provides" appear in
a couple of the base Scala library code - I include them just for
testing the user-defined tags capability.

Note that Alt-c and <M-c> may not work on Unix systems, hence
I map in command mode "cm" to call the ScalaCommentWriter function.

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
scala_commenter.zip 3.0.3 2012-08-24 7.0 richard emberson Changed version number for type to kind delta
scala_commenter.zip 3.0.2 2012-07-30 7.3 richard emberson Vim 7.3 could not handle construct: call funcReturnDictionary().someFunc()
scala_commenter.zip 3.0 2012-07-27 7.0 richard emberson Support for autoloading.
Uses latest version of Self library
scalacommenter.vim 2.2 2010-05-10 7.0 richard emberson Minor correction: could not handle parameters with templates with commas:
  def getAtomicVars(atomicMethods: List[XMethodInfo], methods: HashMap[global.Symbol, XMethodInfo], vars: HashMap[global.Symbol, XVarInfo]) : List[XVarInfo] = {
scalacommenter.vim 2.1 2010-04-24 7.0 richard emberson Very minor: Method recognition failed for the List methods: '::', ':::' and 'reverse_:::'.
scalacommenter.vim 2.0 2010-04-22 7.0 richard emberson Refactored comment generation code using Self.vim, the Vim
  dictionary-base object prototype system. Unified the code that
  generated output for both the writing and re-formatting of
Throw tags are now sorted in alphabetical order
Unified the comment writing code so that comment formatting,
  first comment generation, and subsequent generation all
  use the came code.
Text associated with an existing comment tag is no longer lost.
Add b:scommenter_top_level_tparams_only which controls if all
  template parameters have @tparam tags generated or only those
  at the top-level have tags generated.
Fixed scanning parameters, now scans past qualifiers like 'val',
Supports curried notations func(a: A)(b: B).
'var' or 'private var', etc.
Added b:scommenter_extra_line_text_offset allowing the user to control
  the offset of any additional text associated with a tag.
There is now a b:scommenter_user_tags configuration variable allowing
  the user to register in their .vimrc file third-party tags.
Added b:scommenter_warning_message_enable which controls the printing
  of warning messages (if any)
Added b:scommenter_line_between_user_unknown_and_std_tags which
  controls if a single comment line is printed between the
  user/unknown tags and the standard tags.
Added b:scommenter_user_unknown_before_std_tags which controls the
  order of formatting of the user/unknown tags and the standard tags.
Added b:scommenter_warn_deleted_tags which allows the user to
  save the text from tags deleted during re-formatting.
Supports capturing parameter template @specialized information
  in comments.
The @deprecated(text) annotation now becomes a ScalaDoc @deprecated
   tag (just as the @throws annotation does).
scalacommenter.vim 1.0 2010-04-09 7.2 richard emberson Initial upload
ip used for rating:

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.
SourceForge.net Logo