323 lines
11 KiB
XML
323 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
<document xmlns="http://maven.apache.org/XDOC/2.0"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
|
|
|
|
<properties>
|
|
<title>Headers</title>
|
|
<author>Checkstyle Development Team</author>
|
|
</properties>
|
|
|
|
<head>
|
|
<title>Headers</title>
|
|
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
|
|
<script type="text/javascript" src="js/anchors.js"></script>
|
|
<script type="text/javascript" src="js/google-analytics.js"></script>
|
|
<link rel="icon" href="images/favicon.png" type="image/x-icon" />
|
|
<link rel="shortcut icon" href="images/favicon.ico" type="image/ico" />
|
|
</head>
|
|
|
|
<body>
|
|
<section name="Content">
|
|
<macro name="toc">
|
|
<param name="fromDepth" value="1"/>
|
|
<param name="toDepth" value="1"/>
|
|
</macro>
|
|
</section>
|
|
|
|
<section name="Header">
|
|
<subsection name="Description">
|
|
<p>
|
|
Checks that a source file begins with a specified header. Property
|
|
<code> headerFile</code> specifies a file that contains
|
|
the required header. Alternatively, the header specification can be
|
|
set directly in the <code>header</code> property
|
|
without the need for an external file.
|
|
</p>
|
|
|
|
<p>
|
|
Property <code>ignoreLines</code> specifies the line
|
|
numbers to ignore when matching lines in a header file. This
|
|
property is very useful for supporting headers that contain
|
|
copyright dates. For example, consider the following header:
|
|
</p>
|
|
|
|
<source>
|
|
line 1: ////////////////////////////////////////////////////////////////////
|
|
line 2: // checkstyle:
|
|
line 3: // Checks Java source code for adherence to a set of rules.
|
|
line 4: // Copyright (C) 2002 Oliver Burn
|
|
line 5: ////////////////////////////////////////////////////////////////////
|
|
</source>
|
|
|
|
<p>
|
|
Since the year information will change over time, you can tell
|
|
Checkstyle to ignore line 4 by setting property <code>ignoreLines</code> to <code> 4</code>.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="Properties">
|
|
<table>
|
|
<tr>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>headerFile</td>
|
|
<td>name of the file containing the required header</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><code>null</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>charset</td>
|
|
<td>character encoding to use when reading the headerFile</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td>the charset property of the parent
|
|
<a href="config.html#Checker">Checker</a> module</td>
|
|
</tr>
|
|
<tr>
|
|
<td>header</td>
|
|
<td>
|
|
the required header specified inline. Individual header lines
|
|
must be separated by the string <code>"\n"</code> (even on platforms with a
|
|
different line separator), see examples below.
|
|
</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><code>null</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>ignoreLines</td>
|
|
<td>line numbers to ignore</td>
|
|
<td><a href="property_types.html#intSet">list of integers</a></td>
|
|
<td><code>{}</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>fileExtensions</td>
|
|
<td>file type extension of files to process</td>
|
|
<td><a href="property_types.html#stringSet">String Set</a></td>
|
|
<td><code>{}</code></td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
|
|
<subsection name="Example">
|
|
<p>
|
|
To configure the check to use header file <code>"java.header"</code> and ignore lines <code>2</code>, <code>3</code>, and <code> 4</code> and only process Java files:
|
|
</p>
|
|
|
|
<source>
|
|
<module name="Header">
|
|
<property name="headerFile" value="java.header"/>
|
|
<property name="ignoreLines" value="2, 3, 4"/>
|
|
<property name="fileExtensions" value="java"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
To configure the check to verify that each file starts with the
|
|
header
|
|
</p>
|
|
<source>
|
|
// Copyright (C) 2004 MyCompany
|
|
// All rights reserved
|
|
</source>
|
|
|
|
<p>
|
|
without the need for an external header file:
|
|
</p>
|
|
<source>
|
|
<module name="Header">
|
|
<property name="header"
|
|
value="// Copyright (C) 2004 MyCompany\n// All rights reserved"/>
|
|
</module>
|
|
</source>
|
|
</subsection>
|
|
|
|
<subsection name="Package">
|
|
<p> com.puppycrawl.tools.checkstyle.checks.header </p>
|
|
</subsection>
|
|
|
|
<subsection name="Parent Module">
|
|
<p>
|
|
<a href="config.html#Checker">Checker</a>
|
|
</p>
|
|
</subsection>
|
|
</section>
|
|
|
|
<section name="RegexpHeader">
|
|
<subsection name="Description">
|
|
<p>
|
|
Checks the header of a source file against a header that contains a
|
|
<a
|
|
href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">regular
|
|
expression</a> for each line of the source header.
|
|
</p>
|
|
|
|
<p>
|
|
Rationale: In some projects <a href="#Header">checking against a
|
|
fixed header</a> is not sufficient, e.g. the header might require a
|
|
copyright line where the year information is not static.
|
|
</p>
|
|
|
|
<p>
|
|
For example, consider the following header:
|
|
</p>
|
|
<source>
|
|
line 1: ^/{71}$
|
|
line 2: ^// checkstyle:$
|
|
line 3: ^// Checks Java source code for adherence to a set of rules\.$
|
|
line 4: ^// Copyright \(C\) \d\d\d\d Oliver Burn$
|
|
line 5: ^// Last modification by \$Author.*\$$
|
|
line 6: ^/{71}$
|
|
line 7:
|
|
line 8: ^package
|
|
line 9:
|
|
line 10: ^import
|
|
line 11:
|
|
line 12: ^/\*\*
|
|
line 13: ^ \*([^/]|$)
|
|
line 14: ^ \*/
|
|
</source>
|
|
|
|
<p>
|
|
Lines 1 and 6 demonstrate a more compact notation for 71 '/'
|
|
characters. Line 4 enforces that the copyright notice includes a
|
|
four digit year. Line 5 is an example how to enforce revision
|
|
control keywords in a file header. Lines 12-14 is a template for
|
|
javadoc (line 13 is so complicated to remove conflict with and of
|
|
javadoc comment).
|
|
</p>
|
|
|
|
<p>
|
|
Different programming languages have different comment syntax
|
|
rules, but all of them start a comment with a non-word
|
|
character. Hence you can often use the non-word character
|
|
class to abstract away the concrete comment syntax and allow
|
|
checking the header for different languages with a single
|
|
header definition. For example, consider the following header
|
|
specification (note that this is not the full Apache license
|
|
header):
|
|
</p>
|
|
<source>
|
|
line 1: ^#!
|
|
line 2: ^<\?xml.*>$
|
|
line 3: ^\W*$
|
|
line 4: ^\W*Copyright 2006 The Apache Software Foundation or its licensors, as applicable\.$
|
|
line 5: ^\W*Licensed under the Apache License, Version 2\.0 \(the "License"\);$
|
|
line 6: ^\W*$
|
|
</source>
|
|
|
|
<p>
|
|
Lines 1 and 2 leave room for technical header lines, e.g. the
|
|
"#!/bin/sh" line in Unix shell scripts, or the XML file header
|
|
of XML files. Set the multiline property to "1, 2" so these
|
|
lines can be ignored for file types where they do no apply.
|
|
Lines 3 through 6 define the actual header content. Note how
|
|
lines 2, 4 and 5 use escapes for characters that have special
|
|
regexp semantics.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="Properties">
|
|
<table>
|
|
<tr>
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>headerFile</td>
|
|
<td>name of the file containing the required header</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><code>null</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>charset</td>
|
|
<td>character encoding to use when reading the headerFile</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td>the charset property of the parent
|
|
<a href="config.html#Checker">Checker</a> module</td>
|
|
</tr>
|
|
<tr>
|
|
<td>header</td>
|
|
<td>
|
|
the required header specified inline. Individual header lines
|
|
must be separated by the string <code>"\n"</code> (even on platforms with a
|
|
different line separator), and regular expressions must not span
|
|
multiple lines.
|
|
</td>
|
|
<td><a href="property_types.html#string">string</a></td>
|
|
<td><code>null</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>multiLines</td>
|
|
<td>line numbers to repeat (zero or more times)</td>
|
|
<td><a href="property_types.html#intSet">list of integers</a></td>
|
|
<td><code>{}</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>fileExtensions</td>
|
|
<td>file type extension of files to process</td>
|
|
<td><a href="property_types.html#stringSet">String Set</a></td>
|
|
<td><code>{}</code></td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
|
|
<subsection name="Example">
|
|
<p>
|
|
To configure the check to use header file <code>"java.header"</code> and <code>10</code> and <code>13</code> muli-lines:
|
|
</p>
|
|
<source>
|
|
<module name="RegexpHeader">
|
|
<property name="headerFile" value="java.header"/>
|
|
<property name="multiLines" value="10, 13"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
To configure the check to verify that each file starts with the
|
|
header
|
|
</p>
|
|
<source>
|
|
^// Copyright \(C\) (\d\d\d\d -)? 2004 MyCompany$
|
|
^// All rights reserved$
|
|
</source>
|
|
|
|
<p>
|
|
without the need for an external header file:
|
|
</p>
|
|
<source>
|
|
<module name="RegexpHeader">
|
|
<property
|
|
name="header"
|
|
value="^// Copyright \(C\) (\d\d\d\d -)? 2004 MyCompany$\n^// All rights reserved$"/>
|
|
</module>
|
|
</source>
|
|
|
|
<p>
|
|
<u>Note</u>: <code>ignoreLines</code> property has been
|
|
removed from this check to simplify it. To make some line optional
|
|
use "^.*$" regexp for this line.
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="Package">
|
|
<p>
|
|
com.puppycrawl.tools.checkstyle.checks.header
|
|
</p>
|
|
</subsection>
|
|
|
|
<subsection name="Parent Module">
|
|
<p>
|
|
<a href="config.html#Checker">Checker</a>
|
|
</p>
|
|
</subsection>
|
|
</section>
|
|
</body>
|
|
</document>
|