libgo/go/go/doc/headscan.go

   1 // Copyright 2011 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         The headscan command extracts comment headings from package files;
   7         it is used to detect false positives which may require an adjustment
   8         to the comment formatting heuristics in comment.go.
   9
  10         Usage: headscan [-root root_directory]
  11
  12         By default, the $GOROOT/src directory is scanned.
  13 */
  14 package main
  15
  16 import (
  17         "bytes"
  18         "flag"
  19         "fmt"
  20         "go/doc"
  21         "go/parser"
  22         "go/token"
  23         "os"
  24         "path/filepath"
  25         "runtime"
  26         "strings"
  27 )
  28
  29 var (
  30         root    = flag.String("root", filepath.Join(runtime.GOROOT(), "src"), "root of filesystem tree to scan")
  31         verbose = flag.Bool("v", false, "verbose mode")
  32 )
  33
  34 const (
  35         html_h    = "<h3>"
  36         html_endh = "</h3>\n"
  37 )
  38
  39 func isGoFile(fi os.FileInfo) bool {
  40         return strings.HasSuffix(fi.Name(), ".go") &&
  41                 !strings.HasSuffix(fi.Name(), "_test.go")
  42 }
  43
  44 func appendHeadings(list []string, comment string) []string {
  45         var buf bytes.Buffer
  46         doc.ToHTML(&buf, comment, nil)
  47         for s := buf.String(); ; {
  48                 i := strings.Index(s, html_h)
  49                 if i < 0 {
  50                         break
  51                 }
  52                 i += len(html_h)
  53                 j := strings.Index(s, html_endh)
  54                 if j < 0 {
  55                         list = append(list, s[i:]) // incorrect HTML
  56                         break
  57                 }
  58                 list = append(list, s[i:j])
  59                 s = s[j+len(html_endh):]
  60         }
  61         return list
  62 }
  63
  64 func main() {
  65         flag.Parse()
  66         fset := token.NewFileSet()
  67         nheadings := 0
  68         err := filepath.Walk(*root, func(path string, fi os.FileInfo, err error) error {
  69                 if !fi.IsDir() {
  70                         return nil
  71                 }
  72                 pkgs, err := parser.ParseDir(fset, path, isGoFile, parser.ParseComments)
  73                 if err != nil {
  74                         if *verbose {
  75                                 fmt.Fprintln(os.Stderr, err)
  76                         }
  77                         return nil
  78                 }
  79                 for _, pkg := range pkgs {
  80                         d := doc.NewPackageDoc(pkg, path)
  81                         list := appendHeadings(nil, d.Doc)
  82                         for _, d := range d.Consts {
  83                                 list = appendHeadings(list, d.Doc)
  84                         }
  85                         for _, d := range d.Types {
  86                                 list = appendHeadings(list, d.Doc)
  87                         }
  88                         for _, d := range d.Vars {
  89                                 list = appendHeadings(list, d.Doc)
  90                         }
  91                         for _, d := range d.Funcs {
  92                                 list = appendHeadings(list, d.Doc)
  93                         }
  94                         if len(list) > 0 {
  95                                 // directories may contain multiple packages;
  96                                 // print path and package name
  97                                 fmt.Printf("%s (package %s)\n", path, pkg.Name)
  98                                 for _, h := range list {
  99                                         fmt.Printf("\t%s\n", h)
 100                                 }
 101                                 nheadings += len(list)
 102                         }
 103                 }
 104                 return nil
 105         })
 106         if err != nil {
 107                 fmt.Fprintln(os.Stderr, err)
 108                 os.Exit(1)
 109         }
 110         fmt.Println(nheadings, "headings found")
 111 }