Enhancement: detect wrong deprecation markers

[babakks]

Follow up to #36 (comment).

The correct usage of deprecations is exactly a Deprecation: (with whitespace) marker at the beginning of a paragraph. We can introduce a new rule, probably enabled by default, to detect wrong usages like these:

• DEPRECATED: (See Deprecations are not marked correctly kubernetes/kubernetes#133566)
• DEPRECATED: (no trailing whitespace)
• deprecated:
• deprecated: (no trailing whitespace)

[babakks]

A note on the implementation.

The correct usage of deprecation markers is to put them at the beginning of a paragraph (i.e. not a heading, code block, etc). Also the syntax is strict and must only be "Deprecated: " (case-sensitive and with the trailing whitespace).

However, not all wrong usages are reliably discoverable. For example:

// Foo is a symbol.
// deprecated: use Bar.
func Foo() {}

In this cases, the "deprecated: " marker is at the beginning of a new line, but as of godoc parser, it's just in the middle of the paragraph started at the top line. There might be some smart ways to detect these cases, but the problem is there will be false-positives to them. For instance, a valid case like this should never be detected as a wrong usage:

// Foo is a symbol but here are the reasons why it's
// deprecated: blah, blah, ...
func Foo() {}

Needless to say we don't want to deal with human language complexities.

[babakks]

FWIW running the rule on K8s' master returns these two cases:

./pkg/apis/core/types.go:1132:1: deprecation note should be formatted as "Deprecated: "
./cmd/kubeadm/app/apis/kubeadm/v1beta3/doc.go:22:1: deprecation note should be formatted as "Deprecated: "

The PR for kubernetes/kubernetes#133566 has fixxed lots of issues, but as I ran the linter on the same master SHA, most of the files changed in the PR are intentionally excluded from the Go analysis reach by Go workspace setups.