[インデックス 14759] ファイルの概要

このコミットは、Go言語の公式ドキュメント内のgodocへのリンクにおけるID属性の修正を目的としています。具体的には、godocが生成するHTML要素のID属性の命名規則が変更されたことに伴い、既存のドキュメント内のアンカーリンクを新しいID属性に合わせるように更新しています。これにより、リンク切れを防ぎ、ドキュメントの正確性を保っています。

コミット

commit be7c0f31c798c0c826e7b92d705a270f2e870ca5
Author: Péter Surányi <speter.go1@gmail.com>
Date:   Sat Dec 29 10:41:39 2012 +1100

    doc: fix id attributes in links to godoc
    
    CL6449105 changed godoc id attributes to ensure uniqueness.
    This CL updates links to godoc pages in documents that used
    the old id attributes.
    
    R=golang-dev, dsymonds
    CC=golang-dev, speter.go1
    https://golang.org/cl/7015051

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/be7c0f31c798c0c826e7b92d705a270f2e870ca5

元コミット内容

このコミットの元の内容は、「doc: godocへのリンクにおけるID属性の修正」です。コミットメッセージによると、CL6449105という変更リスト（Change List）によってgodocが生成するID属性が、一意性を確保するために変更されました。この変更リスト（本コミット）は、その古いID属性を使用していたドキュメント内のgodocページへのリンクを更新するものです。

変更の背景

この変更の背景には、godocが生成するHTMLドキュメント内のID属性の重複問題がありました。godocはGoのソースコードからドキュメントを自動生成するツールであり、生成されるHTMLには、パッケージ、関数、変数、型などの各要素に一意のIDが割り当てられ、それらへの直接リンク（アンカーリンク）が可能になります。

しかし、特定の条件下でこれらのID属性が重複する可能性があり、これがドキュメント内のリンクの動作に問題を引き起こすことがありました。例えば、異なるパッケージであっても、同じ名前のセクション（例: "Bugs"セクション）が存在する場合、生成されるIDが重複し、意図しないリンク先に飛んでしまうなどの問題が発生していました。

CL6449105（"godoc: make section ids unique across packages"）は、このID属性の重複問題を解決するために導入されました。この変更により、godocはID属性にpkg-というプレフィックスを追加するなどして、より一意性の高いIDを生成するようになりました。例えば、以前は単に#bugsだったIDが#pkg-bugsのようになることで、bytesパッケージのbugsセクションとfmtパッケージのbugsセクションが明確に区別されるようになりました。

本コミットは、このCL6449105によるgodocのID属性変更に対応し、Goの公式ドキュメント（doc/articles/godoc_documenting_go_code.htmlとdoc/go1.html）内に存在する古いID属性を使用したリンクを、新しい命名規則に準拠するように更新するために行われました。これにより、ドキュメント内のリンクが正しく機能し続けることが保証されます。

前提知識の解説

• godoc: godocはGo言語の公式ドキュメンテーションツールです。Goのソースコードからコメントや宣言を解析し、HTML形式のドキュメントを自動生成します。これにより、開発者はコードとドキュメントを密接に連携させることができます。godocは、Goの標準ライブラリのドキュメント（https://pkg.go.dev/）の生成にも使用されています。
• HTMLのID属性 (id): HTML要素に一意の識別子を付与するための属性です。ウェブページ内で特定の要素をJavaScriptで操作したり、CSSでスタイルを適用したり、あるいはアンカーリンク（<a>タグのhref属性で#id形式で指定）のターゲットとして使用したりするために利用されます。HTMLドキュメント内で同じid属性値を持つ要素は存在してはならないというルールがあります。
• アンカーリンク: HTMLドキュメント内の特定の位置に直接ジャンプするためのリンクです。<a>タグのhref属性に#に続けてターゲットとなる要素のid属性値を指定することで作成されます。例: <a href="#section-id">セクションへジャンプ</a>。
• Change List (CL): Goプロジェクトの開発プロセスで使われる用語で、一連の変更（コミット）をまとめたものです。通常、Gerritなどのコードレビューシステムで管理され、レビューと承認を経て最終的にメインのコードベースにマージされます。コミットメッセージに記載されているCL6449105やCL7015051は、それぞれ特定の変更リストを指します。

技術的詳細

このコミットの技術的な詳細は、godocがHTMLドキュメントを生成する際のID属性の命名規則の変更と、それに伴う既存ドキュメントの更新に集約されます。

以前のgodocでは、例えばパッケージ内の「Bugs」セクションへのリンクは/pkg/bytes/#bugsのように、セクション名がそのままIDとして使用されていました。しかし、これにより複数のパッケージに同じセクション名が存在する場合（例: bytesパッケージにもbugsセクションがあり、stringsパッケージにもbugsセクションがある場合）、生成されるHTMLドキュメント全体でIDが重複してしまう問題がありました。HTMLの仕様ではIDはドキュメント内で一意である必要があるため、これは問題となります。

CL6449105によって、この問題が解決されました。この変更では、godocが生成するID属性に、そのIDが属するエンティティ（この場合はパッケージ）を示すプレフィックスを追加するようになりました。具体的には、パッケージ内のセクションIDにはpkg-というプレフィックスが付加されるようになりました。

• 旧: #bugs
• 新: #pkg-bugs

同様に、パッケージ内の変数セクションや例（examples）セクションなども、同様のプレフィックスルールが適用されました。

• 旧: #variables → 新: #pkg-variables
• 旧: #examples → 新: #pkg-examples

このコミットは、このgodocのID生成ロジックの変更を受けて、Goの公式ドキュメントであるdoc/articles/godoc_documenting_go_code.htmlとdoc/go1.html内の既存のアンカーリンクを修正するものです。これらのファイルは、godocによって生成されたドキュメントへのリンクを含んでおり、godocのID属性の変更に合わせて、リンク先のID属性も更新する必要がありました。

変更は単純な文字列置換であり、古いID属性（例: #bugs）を新しいID属性（例: #pkg-bugs）に置き換えることで、リンクが正しく機能するようにしています。これは、ドキュメントの整合性を保ち、ユーザーが正しい情報にアクセスできるようにするための重要なメンテナンス作業です。

コアとなるコードの変更箇所

diff --git a/doc/articles/godoc_documenting_go_code.html b/doc/articles/godoc_documenting_go_code.html
index 36c9b60d05..7bcca5ad41 100644
--- a/doc/articles/godoc_documenting_go_code.html
+++ b/doc/articles/godoc_documenting_go_code.html
@@ -83,7 +83,7 @@ godoc's output, with one notable exception. Top-level comments that begin with
 the word <code>"BUG(who)"</code> are recognized as known bugs, and included in
 the "Bugs" section of the package documentation. The "who" part should be the
 user name of someone who could provide more information. For example, this is a
-known issue from the <a href="/pkg/bytes/#bugs"><code>bytes</code></a> package:
+known issue from the <a href="/pkg/bytes/#pkg-bugs"><code>bytes</code></a> package:
 </p>

 <pre>
diff --git a/doc/go1.html b/doc/go1.html
index f0a804784a..491fd7bf73 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -1676,7 +1676,7 @@ instead of a <code>Visitor</code> interface value.
 The <code>WalkFunc</code> function will be called even for files or directories that could not be opened;
 in such cases the error argument will describe the failure.
 If a directory's contents are to be skipped,
-the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
+the function should return the value <a href="/pkg/path/filepath/#pkg-variables"><code>filepath.SkipDir</code></a>
 </p>

 {{code "/doc/progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
@@ -1865,7 +1865,7 @@ made easier with the new structure of the packages.
 The imports will be updated by fix tool.\nSingle-template uses will be otherwise be largely unaffected.
 Code that uses multiple templates in concert will need to be updated by hand.
-The <a href="/pkg/text/template/#examples">examples</a> in
+The <a href="/pkg/text/template/#pkg-examples"><code>examples</code></a> in
 the documentation for <code>text/template</code> can provide guidance.
 </p>

コアとなるコードの解説

このコミットでは、以下の2つのファイルが変更されています。

1. doc/articles/godoc_documenting_go_code.html:

   • このファイルは、Goコードのドキュメント化に関する記事です。
   • 変更点:

     -known issue from the <a href="/pkg/bytes/#bugs"><code>bytes</code></a> package:
     +known issue from the <a href="/pkg/bytes/#pkg-bugs"><code>bytes</code></a> package:
     

     bytesパッケージの「Bugs」セクションへのリンクが、#bugsから#pkg-bugsに修正されています。これは、godocが生成するID属性にpkg-プレフィックスが追加されたことに対応するものです。

2. doc/go1.html:

   • このファイルは、Go 1のリリースノートまたは関連ドキュメントです。
   • 変更点1:

     -the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
     +the function should return the value <a href="/pkg/path/filepath/#pkg-variables"><code>filepath.SkipDir</code></a>
     

     path/filepathパッケージの「variables」セクションへのリンクが、#variablesから#pkg-variablesに修正されています。これも同様にpkg-プレフィックスの追加に対応しています。
   • 変更点2:

     -The <a href="/pkg/text/template/#examples">examples</a> in
     +The <a href="/pkg/text/template/#pkg-examples"><code>examples</code></a> in
     

     text/templateパッケージの「examples」セクションへのリンクが、#examplesから#pkg-examplesに修正されています。ここでもpkg-プレフィックスが追加されています。

これらの変更はすべて、godocが生成するHTMLドキュメントのID属性の命名規則が変更されたことに伴い、既存のドキュメント内のアンカーリンクを新しい規則に合わせるためのものです。これにより、ユーザーがこれらのリンクをクリックした際に、意図したセクションに正しくナビゲートされるようになります。

関連リンク

• Go言語の公式ドキュメント: https://pkg.go.dev/
• Goのコードレビューシステム (Gerrit): https://go-review.googlesource.com/ (CLの検索に使用)

参考にした情報源リンク

• https://github.com/golang/go/commit/be7c0f31c798c0c826e7b92d705a270f2e870ca5 (本コミットのGitHubページ)
• https://golang.org/cl/7015051 (本コミットに対応するGoのChange List)
• https://golang.org/cl/6449105 (ID属性の変更を引き起こした元のChange List: "godoc: make section ids unique across packages")
• https://pkg.go.dev/ (godocによって生成されたドキュメントの例)
• HTML id 属性に関する一般的な情報 (例: MDN Web Docs)
• Go言語のドキュメンテーションに関する一般的な情報 (例: Go公式ブログの記事など)