plugins/copyright/docs/README.txt

   1 @NAME@ version @VERSION@ Release Notes for IDEA @IDEA-VERSION@
   2
   3 NOTE: This version requires IDEA to be executed with JDK 1.5.0 or greater.
   4
   5 Project/Module Copyright Notice.
   6
   7 This plugin is used to ensure files in a project or module have a consistent
   8 copyright notice. Copyright notices can be created for the following file
   9 types: Java, JavaScript, JSP, JSPx, XML, HTML, xHTML, DTD, Properties, and CSS.
  10
  11 * Configuration
  12
  13 ** Enable Plugin
  14
  15 By default the plugin is disabled for a project. Simple select the Enable
  16 Copyright Notice Plugin checkbox to enable copyright notices for this project.
  17
  18 ** Project and Module Level
  19
  20 You can set the copyright notice at the project level first. This setting
  21 will be used as the default for each new module added to the project. You
  22 then have the option of adjusting each module's setting individually. For each
  23 module you can specify whether it has it's own custom copyright, uses the
  24 project copyright, or has no copyright at all.
  25
  26 You can also import copyright notice settings from other, external projects and
  27 modules by pressing the Import Settings button. This brings up a file chooser
  28 that lets you select project (*.ipr) or module (*.iml) files. Once selected the
  29 project or module is scanned for copyright plugin settings. If found they are
  30 imported into the current level.
  31
  32 At the module level you can also copy over the current project's settings by
  33 pressing the Copy Project Settings button.
  34
  35 ** Settings
  36
  37 At a given level (project or module) you can define a copyright notice template
  38 to be used by all supported file types and/or you can tailor the copyright
  39 notice settings for a specific file type.
  40
  41 *** Template
  42
  43 **** Text
  44
  45 Most likely you will want the same general copyright notice for all file types.
  46 This is done by setting up the template. The copyright notice template should
  47 be undecorated and language independent. In other words, the template should
  48 not contain any language specific comment markers.
  49
  50 The template will be treated as a Velocity template. See the section below for
  51 more information on Velocity templates.
  52
  53 **** Formatting Options
  54
  55 Once the basic text of the copyright notice is set you can specify several
  56 formatting options.
  57
  58 First you should specify whether the copyright should be entered using a
  59 file's block or line comment syntax. A language not containing the selected
  60 choice will use the syntax it does have available to best emulate the choice. If
  61 the block comment is chosen you have the option of having each line preceded by
  62 a comment marker.
  63
  64 Second you can specify whether the comment should be surrounded by a line of
  65 comment markers, referred to as a separator. If both separators are selected
  66 and are of the same length you will have the option of having the whole comment
  67 "boxed" in. The character used to fill the separator can specified. By default
  68 (nothing specified) the character used will be appropriate for the given
  69 language. Tilde (~) is used for XML type languages because a hypen (-) isn't
  70 valid when strung together.
  71
  72 **** Relative Location
  73
  74 If the area containing the copyright notice contains other, non-copyright
  75 comments you can specify whether the copyright notice comes before or after the
  76 other comments.
  77
  78 You may also specify that you want a blank line to appear after the copyright
  79 notice.
  80
  81 **** Copyright Keyword
  82
  83 This keyword must be a valid Java regular expression (see
  84 java.util.regex.Pattern) used to determine if a comment is a normal comment or a
  85 copyright notice comment. It is important that the keyword expression doesn't
  86 match non-copyright notice comments or you may find comments getting deleted
  87 that you didn't want deleted. This warning is only true for comments near the
  88 beginning of files within the areas that copyright notices may appear. Comments
  89 in other parts of a file will not be effected even if the keyword expression
  90 matches.
  91
  92 **** Preview
  93
  94 Checking the Preview checkbox allows you to see what your comment will look like
  95 using Java comment syntax. This is your entered text formatted with all the
  96 options chosen in the Formatting Options area.
  97
  98 **** Validate
  99
 100 Pressing this button verifies that the text is a valid Velocity template. If
 101 the Velocity engine finds any problem with the text an error message is
 102 displayed. This does not verify whether the resulting comment is valid for the
 103 given file type.
 104
 105 *** File Types
 106
 107 By default all supported file types will use the template copyright notice.
 108 You do have the option of changing the settings for a specific file type.
 109
 110 **** Template Override
 111
 112 No Copyright - Select this if you don't want any copyright notice added to
 113    files of this type. If a copyright notice exists it will be removed.
 114 Use Template - Use the template copyright notice.
 115 Use Template Text - Select this if you want to use the text of the template
 116    copyright notice but you wish to format the text differently.
 117 Fully Custom - Select this if you need to enter a copyright notice in a form
 118    not supported by the supplied formatting options. If you choose this
 119    option then the text you enter must be a complete and valid comment for
 120    the given file type. See the section below on multi-comment notices.
 121
 122 **** Formatting Options
 123
 124 This is only enabled if Use Template Text has been selected. The options work
 125 just as described under the Template section. The only exception is that the
 126 Block and Line comment choices are enabled based on the features of the
 127 language.
 128
 129 **** Alternate Comment Syntax
 130
 131 JSP files can use either JSP comments or XML comments. By default the JSP
 132 syntax is used. To use XML you must check the Use XML Comments checkbox.
 133
 134 **** Relative Location
 135
 136 This is enabled if Use Template Text or Fully Custom has been selected. The
 137 options work just as described under the Template section.
 138
 139 **** File Location
 140
 141 This specifies where within a file the copyright notice is to be placed.
 142
 143 ***** Java
 144
 145 The copyright notice can be placed in one of the following locations:
 146
 147 - At the start of the file before the "package" statement.
 148 - Between the package statement and any imports.
 149 - Between the imports and the first top level class (before the class' Javadoc
 150   comment, if present).
 151
 152 ***** XML/DTD/HTML/xHTML/JSP/JSPx
 153
 154 The copyright notice can be placed in one of the following locations:
 155
 156 - Before the <!DOCTYPE> specification.
 157 - Before the first tag of the document.
 158
 159 ***** All Other File Types
 160
 161 For all other file types the copyright notice must appear in the begining of
 162 the file before any non-comment, non-whitespace content.
 163
 164 * Multi-Comment Notices and Blank Lines
 165
 166 A copyright notice may contain multiple comments. This is a given when using
 167 line comments and the copyright notice contains more than one line of text. You
 168 can also have muliple block comments in a single copyright notice. This can only
 169 happen when using a Fully Custom copyright notice. A Fully Custom copyright
 170 notice also allows for any combination of line and block comments to be used.
 171
 172 There is one very important consideration though when your copyright notice
 173 contains multiple comments - there can't be any blank lines between any of the
 174 comments. Note - this doesn't mean there can't be blank lines in the copyright
 175 notice. They just need to be within a block comment.
 176
 177 If you have a Fully Custom copyright notice with multiple comments and you
 178 place blank lines between any of them, you will most likely get undesirable
 179 effects when you perform copyright updates on files of that type.
 180
 181 * Menus
 182
 183 The option to update the copyright notice will appear in the following
 184 locations:
 185
 186 - At the end of the context menu for a supported file in the project tree.
 187 - At the end of the context menu for a supported file in the packages tree.
 188 - At the end of the context menu for a supported file in an editor.
 189 - At the end of the context menu for a directory in the project tree.
 190 - At the end of the context menu for a package in the packages tree.
 191 - At the end of the context menu for a module in the packages tree.
 192 - At the end of the context menu for a module in the project tree.
 193 - At the end of the Code menu if the current editor contains a supported file.
 194 - At the end of the Generate popup menu if the current editor contains a
 195   supported file.
 196
 197 Selecting a file or directory in the project tree works just like Optimize
 198 Imports. You will have the option of updating a single file or the whole
 199 directory.
 200
 201 New files will automatically have the correct copyright notice applied to them
 202 if the file is a supported type and the file type has copyright notices enabled.
 203
 204 * Copyright Template
 205
 206 The contents of the copyright notice can be plain text or a Velocity template.
 207 See http://jakarta.apache.org/velocity for more information on Velocity and see
 208 http://jakarta.apache.org/velocity/user-guide.html for more details on writing
 209 Velocity templates.
 210
 211 Currently the following variables are available in the Velocity context:
 212
 213 Name                     Type     Comment
 214 ======================== ======== ============================================
 215 $today                   DateInfo Represents the current date and time
 216 $file.fileName           String   The current file's name
 217 $file.pathName           String   The current file's complete path and name
 218 $file.className          String   The current java file's classname
 219 $file.qualifiedClassName String   The current java file's fully qualified name
 220 $file.lastModified       DataInfo The date and time the file was last changed
 221 $project.name            String   The current project's name
 222 $module.name             String   The current module's name
 223 $username                String   The user's name
 224
 225 DateInfo has the following properties:
 226
 227 Name                     Type     Comment
 228 ======================== ======== ============================================
 229 year                     int      The date's year
 230 month                    int      The date's month (1 - 12)
 231 day                      int      The date's day of month (1 - 31)
 232 hour                     int      The date's hour (0 - 23)
 233 minute                   int      The date's minute of the hour (0 - 59)
 234 second                   int      The date's second of the minute (0 - 59)
 235
 236 DateInfo has the following method:
 237
 238 Name                     Type     Comment
 239 ======================== ======== ============================================
 240 format(String format)    String   See java.text.SimpleDateFormat format options
 241