_content: link to definition of "first sentence"
Fixes golang/go#59206
Change-Id: Ib3b92614acbceb5452c2a5d08623cc2e6cf5b182
Reviewed-on: https://go-review.googlesource.com/c/website/+/496495
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
diff --git a/_content/blog/godoc.md b/_content/blog/godoc.md
index dd108f4..f5ade6c 100644
--- a/_content/blog/godoc.md
+++ b/_content/blog/godoc.md
@@ -74,8 +74,9 @@
[doc.go](/src/pkg/encoding/gob/doc.go),
which contains only those comments and a package clause.
-When writing package comments of any size,
-keep in mind that their first sentence will appear in godoc's [package list](/pkg/).
+When writing a package comment of any size,
+keep in mind that its [first sentence](/pkg/go/doc/#Package.Synopsis)
+will appear in godoc's [package list](/pkg/).
Comments that are not adjacent to a top-level declaration are omitted from godoc's output,
with one notable exception.
diff --git a/_content/doc/comment.md b/_content/doc/comment.md
index 4c8715e..f945ecf 100644
--- a/_content/doc/comment.md
+++ b/_content/doc/comment.md
@@ -49,7 +49,8 @@
The square brackets in `[path/filepath]` create a [documentation link](#links).
As can be seen in this example, Go doc comments use complete sentences.
-For a package comment, that means the first sentence begins with “Package <name>”.
+For a package comment, that means the [first sentence](/pkg/go/doc/#Package.Synopsis)
+begins with “Package <name>”.
For multi-file packages, the package comment should only be in one source file.
If multiple files have package comments, they are concatenated to form one
