usr/src/tools/scripts/jstyle.1onbld

   1 .\" Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
   2 .\" Use is subject to license terms.
   3 .\"
   4 .\" CDDL HEADER START
   5 .\"
   6 .\" The contents of this file are subject to the terms of the
   7 .\" Common Development and Distribution License (the "License").
   8 .\" You may not use this file except in compliance with the License.
   9 .\"
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  11 .\" or http://www.opensolaris.org/os/licensing.
  12 .\" See the License for the specific language governing permissions
  13 .\" and limitations under the License.
  14 .\"
  15 .\" When distributing Covered Code, include this CDDL HEADER in each
  16 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  17 .\" If applicable, add the following below this CDDL HEADER, with the
  18 .\" fields enclosed by brackets "[]" replaced with your own identifying
  19 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  20 .\"
  21 .\" CDDL HEADER END
  22 .\"
  23 .TH JSTYLE 1ONBLD "Feb 22, 2017"
  24 .SH NAME
  25 .I jstyle
  26 \- check for some common stylistic errors in Java source files
  27 .SH SYNOPSIS
  28 \fBjstyle [-chptvC] [file...]\fP
  29 .SH DESCRIPTION
  30 .LP
  31 .B jstyle
  32 inspects Java source files (*.java) for common stylistic errors.  It
  33 is similar to
  34 .BR cstyle (1ONBLD)
  35 in that it attempts to check for the style
  36 documented in \fIcstyle.ms.pdf\fP, although by
  37 necessity is modified to work with Java-specific constructs.  Note that
  38 there is much in that document that
  39 .I cannot
  40 be checked for; just because your code is
  41 .BR jstyle (1ONBLD)
  42 clean does not
  43 mean that you've followed illumos Java style.  \fICaveat emptor\fP.
  44 .SH OPTIONS
  45 .LP
  46 The following options are supported:
  47 .TP 4
  48 .B \-c
  49 Check continuation line indentation inside of functions.  illumos C style
  50 states that all statements must be indented to an appropriate tab stop,
  51 and any continuation lines after them must be indented \fIexactly\fP four
  52 spaces from the start line.  This option enables a series of checks
  53 designed to find continuation line problems within functions only.
  54 .TP 4
  55 .B \-h
  56 Performs heuristic checks that are sometimes wrong.  Not generally used.
  57 .TP 4
  58 .B \-p
  59 Performs some of the more picky checks.  You should generally use this.
  60 .TP 4
  61 .B \-t
  62 Insists on indentation with tabs.  Because of the depth of nested blocks
  63 that Java requires, and the commonality of long identifiers, tab
  64 indentation in Java code is not always useful, assuming that tabs are fixed
  65 at eight columns and that maximum line length is fixed at eighty columns,
  66 so this option is not on by default.  If you choose to consider tabs to be
  67 four columns wide (not acceptable for ON), or are writing simple enough
  68 code that the nesting is not very deep, this option might be useful.
  69 Otherwise, avoid it.
  70 .TP 4
  71 .B \-v
  72 Verbose output; includes the text of the line of error.
  73 .TP 4
  74 .B \-C
  75 Ignore errors in header comments (i.e., block comments starting in the
  76 first column).  Not generally used.
  77 .SH NOTES
  78 .LP
  79 The jstyle rule for the illumos gate is that all new files must
  80 be
  81 .B -p
  82 clean.  For existing files, the following invocations are
  83 run against both the old and new files:
  84 .TP 4
  85 .B "jstyle file"
  86 .TP 4
  87 .B "jstyle -p file"
  88 .LP
  89 If the old file gave no errors for one of the invocations, the new file
  90 must also give no errors.  This way, files cannot become unclean.
  91 .SH BUGS
  92 .LP
  93 .BR jstyle (1ONBLD)
  94 cannot disambiguate Java generic type parameters or
  95 arguments that span multiple lines from relational operators.  For example:
  96 .RS 4
  97 .HP 4
  98 private class Foo<A extends Bar,
  99 .br
 100 B extends Bar> { ...
 101 .RE
 102 .LP
 103 is flagged as two lines with missing spaces around relational operators.