diff options
| author | Adam Langley <agl@google.com> | 2015-11-05 01:05:00 +0300 |
|---|---|---|
| committer | Adam Langley <agl@google.com> | 2015-11-05 23:12:45 +0300 |
| commit | 5f88999a1edd11d8b5e8a72a627a5714c95373cf (patch) | |
| tree | f8b11cc4b02f96b596a72247d08b8a88426dbcd0 /util | |
| parent | e57a19203fca0cfe413ad23b08bfce4f8fd59023 (diff) | |
Fix up several comments and detect problems in the future.
This change fixes up several comments (many of which were spotted by
Kenny Root) and also changes doc.go to detect cases where comments don't
start with the correct word. (This is a common error.)
Since we have docs builders now, these errors will be found
automatically in the future.
Change-Id: I58c6dd4266bf3bd4ec748763c8762b1a67ae5ab3
Reviewed-on: https://boringssl-review.googlesource.com/6440
Reviewed-by: Adam Langley <agl@google.com>
Diffstat (limited to 'util')
| -rw-r--r-- | util/doc.go | 13 |
1 files changed, 13 insertions, 0 deletions
diff --git a/util/doc.go b/util/doc.go index ce7a3e80..7d15d9ba 100644 --- a/util/doc.go +++ b/util/doc.go @@ -388,6 +388,19 @@ func (config *Config) parseHeader(path string) (*HeaderFile, error) { if last := len(section.Decls) - 1; len(name) == 0 && len(comment) == 0 && last >= 0 { section.Decls[last].Decl += "\n" + decl } else { + // As a matter of style, comments should start + // with the name of the thing that they are + // commenting on. We make an exception here for + // #defines (because we often have blocks of + // them) and collective comments, which are + // detected by starting with “The” or “These”. + if len(comment) > 0 && + !strings.HasPrefix(comment[0], name) && + !strings.HasPrefix(decl, "#define ") && + !strings.HasPrefix(comment[0], "The ") && + !strings.HasPrefix(comment[0], "These ") { + return nil, fmt.Errorf("Comment for %q doesn't seem to match just above %s:%d\n", name, path, lineNo) + } anchor := sanitizeAnchor(name) // TODO(davidben): Enforce uniqueness. This is // skipped because #ifdefs currently result in |