Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

このコミットは、Go言語の公式ドキュメントの一部である doc/go1.html ファイルに対する変更です。go1.html は、Go 1のリリースノートまたは主要な変更点をまとめたドキュメントであると推測されます。このファイルは、Go言語の進化における重要なマイルストーンであるGo 1リリースに関する情報を提供しており、特にGo言語の標準ライブラリやツールにおけるAPIの変更点について記述されています。

コミット

  • コミットハッシュ: 6923f6d12aad4fb196bff109f091b042a2d17f39
  • 作者: Robert Griesemer gri@golang.org
  • コミット日時: 2012年1月20日 金曜日 12:57:43 -0800
  • 変更ファイル: doc/go1.html (1ファイル)
  • 変更行数: 40行変更 (21行追加, 19行削除)

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

https://github.com/golang/go/commit/6923f6d12aad4fb196bff109f091b042a2d17f39

元コミット内容

doc/go1.html: fix broken links

R=r
CC=golang-dev
https://golang.org/cl/5555060

変更の背景

このコミットの主な目的は、doc/go1.html 内に存在する壊れたリンク（broken links）を修正することです。Go言語のドキュメントは、その構造や提供方法が時間とともに変化する可能性があります。特に、Go 1のリリースという大きな節目において、ドキュメントのパス構造が変更されたり、ドキュメントが提供されるベースURLが変わったりしたことが原因で、既存の相対パスで記述されたリンクが正しく機能しなくなったと考えられます。

具体的には、go/parser/ や go/doc/ といったGoの標準パッケージへのリンクが、相対パスで記述されていたために、ドキュメントが想定とは異なる場所から参照された際にリンク切れを起こしていたと推測されます。このコミットは、これらのリンクを絶対パス形式に修正することで、ドキュメントの整合性とユーザビリティを確保することを目的としています。

前提知識の解説

HTMLにおけるリンクのパス指定

HTMLにおいて、他のリソース（別のHTMLページ、画像、CSSファイルなど）へのリンクを指定する方法には、主に「相対パス」と「絶対パス」の2種類があります。

  1. 相対パス (Relative Path): 現在のドキュメントの位置を基準にして、リンク先の位置を指定する方法です。 例: <a href="page.html"> (同じディレクトリ内の page.html) 例: <a href="../images/pic.png"> (一つ上のディレクトリの images フォルダ内の pic.png) 利点: ドキュメントの階層構造が維持されていれば、ドメインやルートディレクトリの変更に影響されない。 欠点: ドキュメントの移動や、参照元と参照先の相対的な位置関係が変わるとリンクが壊れる可能性がある。

  2. 絶対パス (Absolute Path): ルートディレクトリ（ウェブサイトの最上位ディレクトリ）または完全なURLを基準にして、リンク先の位置を指定する方法です。 例: <a href="/pkg/go/parser/"> (ルートディレクトリからのパス) 例: <a href="https://golang.org/pkg/go/parser/"> (完全なURL) 利点: ドキュメントがどこに移動しても、リンク先が固定されているため、リンクが壊れにくい。 欠点: ドメインやルートディレクトリの変更があった場合、リンクを修正する必要がある。

このコミットでは、相対パスで記述されていたリンクを、ルートディレクトリからの絶対パス（/pkg/... の形式）に修正しています。これにより、doc/go1.html がどこに配置されても、Goのパッケージドキュメントへのリンクが常に /pkg/ を起点として解決されるようになり、リンク切れが解消されます。

Go言語の標準パッケージとドキュメント

Go言語は、豊富な標準ライブラリを提供しており、そのドキュメントはGoの公式ウェブサイト (golang.org) の /pkg/ 以下に公開されています。

  • go/parser パッケージ: Goのソースコードを解析し、抽象構文木 (AST) を構築するためのパッケージです。ParseFile, ParseDir, ParseExpr などの関数を提供します。
  • go/doc パッケージ: Goのソースコードからドキュメントを生成するためのパッケージです。Goのコードコメントを解析し、構造化されたドキュメントデータを作成します。Package, Value, Method などの型が定義されています。
  • go/ast パッケージ: Goの抽象構文木 (AST) を表現するためのデータ構造を定義するパッケージです。CommentGroup や Text メソッドなどが含まれます。
  • go/token パッケージ: Goのソースコードを字句解析する際に使用されるトークンや、ソースコード上の位置情報を扱うためのパッケージです。FileSet や Iterate メソッドなどが含まれます。

これらのパッケージは、GoのツールチェインやIDE、ドキュメンテーションツールなどで広く利用されており、Go言語のコードをプログラム的に扱う上で非常に重要です。doc/go1.html は、Go 1リリースにおけるこれらのパッケージのAPI変更点について説明しているため、正確なリンクが不可欠でした。

技術的詳細

このコミットで行われた技術的な変更は、doc/go1.html ファイル内のHTMLアンカータグ (<a>) の href 属性の値を、相対パスから絶対パスに一括して修正することです。

具体的には、以下のような変更が行われています。

  • href="go/parser/#ParseFile" → href="/pkg/go/parser/#ParseFile"
  • href="go/parser/#ParseDir" → href="/pkg/go/parser/#ParseDir"
  • href="go/parser/#ParseExpr" → href="/pkg/go/parser/#ParseExpr"
  • href="go/doc/" → href="/pkg/go/doc/"
  • href="go/doc/#Package" (新規追加)
  • href="go/doc/#Value" (新規追加)
  • href="go/doc/#Method" (新規追加)
  • href="go/doc/#AllDecls" → href="/pkg/go/doc/#Mode" (リンク先も変更)
  • href="go/ast/#Text" → href="/pkg/go/ast/#CommentGroup.Text" (リンク先も変更)
  • href="go/ast/#CommentGroup" → href="/pkg/go/ast/#CommentGroup"
  • href="go/token/" → href="/pkg/go/token/"
  • href="go/token/#FileSet" → href="/pkg/go/token/#FileSet"
  • href="go/token/#FileSet.Iterate" → href="/pkg/go/token/#FileSet.Iterate"
  • href="go" → href="/pkg/go/"
  • href="go/doc/" → href="/pkg/go/doc/"

これらの変更は、すべて href 属性の先頭に /pkg/ を追加するか、既存の go/ を /pkg/go/ に変更することで、Goのパッケージドキュメントへのリンクが常にルートからの絶対パスとして解決されるようにしています。これにより、doc/go1.html がGoのウェブサイト上のどこに配置されても、リンク切れが発生しない堅牢なドキュメントになります。

また、go/doc/#AllDecls が go/doc/#Mode に、go/ast/#Text が go/ast/#CommentGroup.Text に変更されている箇所もあり、これは単なるパスの修正だけでなく、APIの変更に伴うドキュメント内のアンカー名（フラグメント識別子）の更新も含まれていることを示唆しています。これは、Go 1リリースにおけるAPIの整理と、それに伴うドキュメントの正確性の維持の重要性を強調しています。

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

--- a/doc/go1.html
+++ b/doc/go1.html
@@ -948,19 +948,21 @@ for that purpose.
 <p>
 The set of parse functions provided by the <a href="/pkg/go/parser/"><code>go/parser</code></a>
 package has been reduced to the primary parse function
-<a href="go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
-convenience functions <a href="go/parser/#ParseDir"><code>ParseDir</code></a>
-and <a href="go/parser/#ParseExpr"><code>ParseExpr</code></a>.\n+<a href="/pkg/go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
+convenience functions <a href="/pkg/go/parser/#ParseDir"><code>ParseDir</code></a>
+and <a href="/pkg/go/parser/#ParseExpr"><code>ParseExpr</code></a>.
 </p>
 
 <p>
-The type names of the <a href="go/doc/"><code>go/doc</code></a> package have been
+The type names of the <a href="/pkg/go/doc/"><code>go/doc</code></a> package have been
 streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code>
-is now <code>Package</code>, <code>ValueDoc</code> is <code>Value</code>, etc.\n+is now <a href="/pkg/go/doc/#Package"><code>Package</code></a>, <code>ValueDoc</code>
+is <a href="/pkg/go/doc/#Value"><code>Value</code></a>, etc.
 Also, all types now consistently have a <code>Name</code> field (or <code>Names</code>,\n in the case of type <code>Value</code>), <code>Type.Factories</code> has become
-<code>Type.Funcs</code>, and there is a new type <code>Method</code> that describes
-methods in more detail.\n+<code>Type.Funcs</code>, and there is a new type
+<a href="/pkg/go/doc/#Method"><code>Method</code></a> that describes methods in
+more detail.
 Instead of calling <code>doc.NewPackageDoc(pkg, importpath)</code>,\n documentation for a package is created with:\n </p>\n@@ -970,29 +972,29 @@ documentation for a package is created with:\n </pre>\n 
 <p>
-where the new <code>mode</code> parameter specifies the operation mode:\n-if set to <a href="go/doc/#AllDecls"><code>AllDecls</code></a>, all declarations\n-(not just exported ones) are considered.\n+where the new <code>mode</code> parameter specifies the operation\n+<a href="/pkg/go/doc/#Mode"><code>Mode</code></a>: if set to\n+<code>AllDecls</code>, all declarations (not just exported ones) are considered.\n The function <code>NewFileDoc</code> was removed, and the function\n <code>CommentText</code> has become the method\n-<a href="go/ast/#Text"><code>Text</code></a> of\n-<a href="go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.\n+<a href="/pkg/go/ast/#CommentGroup.Text"><code>Text</code></a> of\n+<a href="/pkg/go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.
 </p>\n 
 <p>
-In package <a href="go/token/"><code>go/token</code></a>, the\n-<a href="go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code>\n+In package <a href="/pkg/go/token/"><code>go/token</code></a>, the\n+<a href="/pkg/go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code>\n (which originally returned a channel of <code>*token.File</code>s) has been replaced\n-with the iterator <a href="go/token/#FileSet.Iterate"><code>Iterate</code></a> that\n+with the iterator <a href="/pkg/go/token/#FileSet.Iterate"><code>Iterate</code></a> that\n accepts a function argument instead.\n </p>\n 
 <p>\n  <em>Updating</em>:\n-Code that uses packages in <code>go</code> will have to be updated by hand; the\n-compiler will reject incorrect uses. Templates used in conjuction with any of the\n-<code>go/doc</code> types may need manual fixes; the renamed fields will lead\n-to run-time errors.\n+Code that uses these packages in <a href="/pkg/go/">go</a> will have to be updated by hand;\n+the compiler will reject incorrect uses. Templates used in conjuction with any of the\n+<a href="/pkg/go/doc/"><code>go/doc</code></a> types may need manual fixes; the renamed\n+fields will lead to run-time errors.\n </p>\n 
 <h3 id=\"exp\">The package tree exp</h3>

コアとなるコードの解説

上記の差分は、doc/go1.html ファイル内のHTMLリンクの href 属性がどのように変更されたかを示しています。

変更のパターンは非常に明確です。

  • 相対パスの go/ を /pkg/go/ に変更: 例えば、<a href="go/parser/#ParseFile"> は <a href="/pkg/go/parser/#ParseFile"> に変更されています。これは、Goのパッケージドキュメントが golang.org/pkg/ 以下に配置されているため、ルートからの絶対パスとして /pkg/ を含めることで、リンクが常に正しく解決されるようにするためです。

  • 既存の /pkg/go/ へのリンクはそのまま: 既に /pkg/go/parser/ のように絶対パスで記述されているリンクは変更されていません。これは、それらのリンクが既に正しく機能していたためです。

  • API変更に伴うアンカー名の修正: 一部のリンクでは、パスだけでなくアンカー名（# 以降の部分）も変更されています。

    • go/doc/#AllDecls が go/doc/#Mode に変更されたのは、go/doc パッケージ内の AllDecls という定数または変数への参照が、より一般的な Mode 型または関連するセクションへの参照に変わったことを示唆しています。これは、Go 1リリースにおけるAPIの整理の一環である可能性があります。
    • go/ast/#Text が go/ast/#CommentGroup.Text に変更されたのは、Text メソッドが ast.CommentGroup 型のメソッドとして明確に指定されるようになったことを反映しています。これは、APIの明確化と、ドキュメントの正確性を高めるための変更です。

これらの変更は、Go 1リリースに伴うドキュメントの構造変更やAPIの最終調整に対応するために行われたものであり、ユーザーがGo 1の変更点を正確に理解し、関連するドキュメントにスムーズにアクセスできるようにするための重要な修正です。

関連リンク

参考にした情報源リンク