github.com/d4l3k/go@v0.0.0-20151015000803-65fc379daeda/src/cmd/vet/doc.go (about)

     1  // Copyright 2010 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  
     7  Vet examines Go source code and reports suspicious constructs, such as Printf
     8  calls whose arguments do not align with the format string. Vet uses heuristics
     9  that do not guarantee all reports are genuine problems, but it can find errors
    10  not caught by the compilers.
    11  
    12  It can be invoked three ways:
    13  
    14  By package, from the go tool:
    15  	go vet package/path/name
    16  vets the package whose path is provided.
    17  
    18  By files:
    19  	go tool vet source/directory/*.go
    20  vets the files named, all of which must be in the same package.
    21  
    22  By directory:
    23  	go tool vet source/directory
    24  recursively descends the directory, vetting each package it finds.
    25  
    26  Vet's exit code is 2 for erroneous invocation of the tool, 1 if a
    27  problem was reported, and 0 otherwise. Note that the tool does not
    28  check every possible problem and depends on unreliable heuristics
    29  so it should be used as guidance only, not as a firm indicator of
    30  program correctness.
    31  
    32  By default all checks are performed. If any flags are explicitly set
    33  to true, only those tests are run. Conversely, if any flag is
    34  explicitly set to false, only those tests are disabled.
    35  Thus -printf=true runs the printf check, -printf=false runs all checks
    36  except the printf check.
    37  
    38  Available checks:
    39  
    40  Assembly declarations
    41  
    42  Flag: -asmdecl
    43  
    44  Mismatches between assembly files and Go function declarations.
    45  
    46  Useless assignments
    47  
    48  Flag: -assign
    49  
    50  Check for useless assignments.
    51  
    52  Atomic mistakes
    53  
    54  Flag: -atomic
    55  
    56  Common mistaken usages of the sync/atomic package.
    57  
    58  Boolean conditions
    59  
    60  Flag: -bool
    61  
    62  Mistakes involving boolean operators.
    63  
    64  Build tags
    65  
    66  Flag: -buildtags
    67  
    68  Badly formed or misplaced +build tags.
    69  
    70  Unkeyed composite literals
    71  
    72  Flag: -composites
    73  
    74  Composite struct literals that do not use the field-keyed syntax.
    75  
    76  Copying locks
    77  
    78  Flag: -copylocks
    79  
    80  Locks that are erroneously passed by value.
    81  
    82  Documentation examples
    83  
    84  Flag: -example
    85  
    86  Mistakes involving example tests, including examples with incorrect names or
    87  function signatures, or that document identifiers not in the package.
    88  
    89  Methods
    90  
    91  Flag: -methods
    92  
    93  Non-standard signatures for methods with familiar names, including:
    94  	Format GobEncode GobDecode MarshalJSON MarshalXML
    95  	Peek ReadByte ReadFrom ReadRune Scan Seek
    96  	UnmarshalJSON UnreadByte UnreadRune WriteByte
    97  	WriteTo
    98  
    99  Nil function comparison
   100  
   101  Flag: -nilfunc
   102  
   103  Comparisons between functions and nil.
   104  
   105  Printf family
   106  
   107  Flag: -printf
   108  
   109  Suspicious calls to functions in the Printf family, including any functions
   110  with these names, disregarding case:
   111  	Print Printf Println
   112  	Fprint Fprintf Fprintln
   113  	Sprint Sprintf Sprintln
   114  	Error Errorf
   115  	Fatal Fatalf
   116  	Log Logf
   117  	Panic Panicf Panicln
   118  The -printfuncs flag can be used to redefine this list.
   119  If the function name ends with an 'f', the function is assumed to take
   120  a format descriptor string in the manner of fmt.Printf. If not, vet
   121  complains about arguments that look like format descriptor strings.
   122  
   123  It also checks for errors such as using a Writer as the first argument of
   124  Printf.
   125  
   126  Struct tags
   127  
   128  Range loop variables
   129  
   130  Flag: -rangeloops
   131  
   132  Incorrect uses of range loop variables in closures.
   133  
   134  Shadowed variables
   135  
   136  Flag: -shadow=false (experimental; must be set explicitly)
   137  
   138  Variables that may have been unintentionally shadowed.
   139  
   140  Shifts
   141  
   142  Flag: -shift
   143  
   144  Shifts equal to or longer than the variable's length.
   145  
   146  Flag: -structtags
   147  
   148  Struct tags that do not follow the format understood by reflect.StructTag.Get.
   149  Well-known encoding struct tags (json, xml) used with unexported fields.
   150  
   151  Unreachable code
   152  
   153  Flag: -unreachable
   154  
   155  Unreachable code.
   156  
   157  Misuse of unsafe Pointers
   158  
   159  Flag: -unsafeptr
   160  
   161  Likely incorrect uses of unsafe.Pointer to convert integers to pointers.
   162  A conversion from uintptr to unsafe.Pointer is invalid if it implies that
   163  there is a uintptr-typed word in memory that holds a pointer value,
   164  because that word will be invisible to stack copying and to the garbage
   165  collector.
   166  
   167  Unused result of certain function calls
   168  
   169  Flag: -unusedresult
   170  
   171  Calls to well-known functions and methods that return a value that is
   172  discarded.  By default, this includes functions like fmt.Errorf and
   173  fmt.Sprintf and methods like String and Error. The flags -unusedfuncs
   174  and -unusedstringmethods control the set.
   175  
   176  Other flags
   177  
   178  These flags configure the behavior of vet:
   179  
   180  	-all (default true)
   181  		Check everything; disabled if any explicit check is requested.
   182  	-v
   183  		Verbose mode
   184  	-printfuncs
   185  		A comma-separated list of print-like functions to supplement the
   186  		standard list.  Each entry is in the form Name:N where N is the
   187  		zero-based argument position of the first argument involved in the
   188  		print: either the format or the first print argument for non-formatted
   189  		prints.  For example, if you have Warn and Warnf functions that
   190  		take an io.Writer as their first argument, like Fprintf,
   191  			-printfuncs=Warn:1,Warnf:1
   192  		For more information, see the discussion of the -printf flag.
   193  	-shadowstrict
   194  		Whether to be strict about shadowing; can be noisy.
   195  	-test
   196  		For testing only: sets -all and -shadow.
   197  */
   198  package main // import "golang.org/x/tools/cmd/vet"