From 257114af91a0defb1fc2c16c7f4ae2429b8a4e0f Mon Sep 17 00:00:00 2001 From: Andrew Gerrand Date: Wed, 27 Jan 2016 16:38:22 +1100 Subject: [PATCH] content: documented godoc's "Deprecated:" convention in the godoc post Fixes golang/go#10909 Change-Id: Ie2553bc2f6983cbcaf7398366c21dc175e1f5453 Reviewed-on: https://go-review.googlesource.com/18956 Reviewed-by: Rob Pike --- content/godoc-documenting-go-code.article | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/godoc-documenting-go-code.article b/content/godoc-documenting-go-code.article index eda08607..72eeeb2e 100644 --- a/content/godoc-documenting-go-code.article +++ b/content/godoc-documenting-go-code.article @@ -37,6 +37,14 @@ Comments that are not adjacent to a top-level declaration are omitted from godoc // BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly. +Sometimes a struct field, function, type, or even a whole package becomes +redundant or unnecessary, but must be kept for compatibility with existing +programs. +To signal that an identifier should not be used, add a paragraph to its doc +comment that begins with "Deprecated:" followed by some information about the +deprecation. +There are a such few examples [[https://golang.org/search?q=deprecated][in the standard library]]. + There are a few formatting rules that Godoc uses when converting comments to HTML: - Subsequent lines of text are considered part of the same paragraph; you must leave a blank line to separate paragraphs.