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

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

このコミットは、Go言語の標準ライブラリ html/template パッケージ内の content.go ファイルにおけるドキュメンテーションのインデント（字下げ）を修正するものです。具体的には、CSSおよびJavaScriptの安全なコンテンツ型に関するコメントの箇条書きの書式が調整されています。

コミット

  • コミットハッシュ: 38c082f69e08d7dbb56392b54a546801224ee239
  • Author: Andrew Gerrand adg@golang.org
  • Date: Fri Nov 25 13:32:44 2011 +1100

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

https://github.com/golang/go/commit/38c082f69e08d7dbb56392b54a546801224ee239

元コミット内容

html/template: fix documentation indent

R=nigeltao
CC=golang-dev
https://golang.org/cl/5437061

変更の背景

このコミットの背景は、Go言語の html/template パッケージのドキュメンテーションの可読性と一貫性を向上させることにあります。Goのコードベースでは、コメントやドキュメンテーションの書式に関する特定のガイドラインや慣習が存在します。このコミットは、html/template/content.go 内の CSS および JSStr 型の定義に関するコメントにおいて、箇条書きのインデントが他のドキュメンテーションと異なっていたり、視覚的に読みにくかったりした点を修正することを目的としています。

特に、箇条書きの項目が数字で始まる場合、その数字の後に続くテキストのインデントが適切でないと、リストの構造が分かりにくくなることがあります。この変更は、ドキュメンテーションの整形を改善し、開発者がコードをより容易に理解できるようにするための、小さな品質改善の一環です。

前提知識の解説

このコミットを理解するためには、以下の前提知識があると役立ちます。

  1. Go言語の html/template パッケージ:

    • html/template パッケージは、Go言語でHTML出力を生成する際に、クロスサイトスクリプティング（XSS）などのセキュリティ脆弱性を自動的に防止するための機能を提供するものです。
    • このパッケージは、テンプレートエンジンとして機能し、ユーザーが提供するデータとテンプレートを組み合わせて最終的なHTMLを生成します。
    • 特に重要なのは、template.HTML, template.CSS, template.JS, template.URL, template.JSStr といった「コンテキストに応じたエスケープ」を行うための特殊な型です。これらの型は、その値が特定のコンテキスト（例: HTML属性、CSSスタイル、JavaScriptコード）において安全であるとマークするために使用されます。これにより、悪意のある入力が意図しないコードとして実行されることを防ぎます。
    • template.CSS はCSSとして安全な文字列を、template.JSStr はJavaScriptの文字列リテラルとして安全な文字列を表します。

  2. CSS3 (Cascading Style Sheets Level 3):

    • ウェブページのスタイルを定義するための言語です。
    • CSS3 stylesheet production はCSS全体の構造を指し、CSS3 rule production はセレクタと宣言ブロックからなる個々のCSSルール（例: p { color: blue; }）を指します。
    • CSS3 declaration productions はプロパティと値のペア（例: color: red;）を指し、CSS3 value production はプロパティに割り当てられる具体的な値（例: rgba(0, 0, 255, 127)）を指します。
    • html/template の CSS 型は、これらのCSS構文のいずれかに合致する安全なコンテンツをカプセル化することを意図しています。

  3. JavaScriptの文字列リテラル:

    • JavaScriptにおいて、文字列は通常、シングルクォート (') またはダブルクォート (") で囲まれます。
    • StringCharacter は文字列リテラル内で許可される文字を指します。これには、バックスラッシュ (\) や改行文字（LineTerminator）を除くソースコードの文字が含まれます。
    • EscapeSequence は、バックスラッシュに続く特殊文字（例: \n で改行、\" でダブルクォート）をエスケープするためのシーケンスです。
    • LineContinuations は、バックスラッシュの直後に改行が続くことで、文字列リテラルを複数行にわたって記述する構文ですが、JavaScriptの古い仕様や特定のコンテキストでは許可されない場合があります。html/template の JSStr 型は、このような LineContinuations を含まない、安全なJavaScript文字列リテラルをカプセル化することを意図しています。

技術的詳細

このコミットは、src/pkg/html/template/content.go ファイル内のコメントの書式設定に関するものです。具体的には、CSS 型と JSStr 型のドキュメンテーションコメントにおける箇条書きのインデントが修正されています。

変更前は、箇条書きの各項目が数字と括弧 (1) の形式で始まり、その後に続くテキストが数字の開始位置からインデントされていました。しかし、これはGoのドキュメンテーションの一般的な慣習や、視覚的な読みやすさの点で最適ではありませんでした。

変更後は、箇条書きの項目が数字とピリオド 1. の形式で始まり、その後に続くテキストが数字の開始位置ではなく、数字とピリオドの後のスペースから適切にインデントされるように修正されています。これにより、箇条書きの構造がより明確になり、各項目が独立した情報として認識しやすくなります。

また、JSStr 型のドキュメンテーションでは、StringCharacter と EscapeSequence の説明部分のインデントも調整されています。変更前は、これらの説明が親の箇条書き項目と同じレベルでインデントされていましたが、変更後は、より深いレベルでインデントされ、親項目に対する補足説明であることが視覚的に分かりやすくなっています。

この変更は、コードの機能的な振る舞いには一切影響を与えません。純粋にドキュメンテーションの品質と可読性を向上させるためのものです。Go言語のプロジェクトでは、コードだけでなく、ドキュメンテーションの品質も非常に重視されており、このような細かな修正もコードベース全体の保守性と理解度を高める上で重要とされています。

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

diff --git a/src/pkg/html/template/content.go b/src/pkg/html/template/content.go
index 3fb15a6e93..4de7ccde91 100644
--- a/src/pkg/html/template/content.go
+++ b/src/pkg/html/template/content.go
@@ -12,10 +12,10 @@ import (
 // Strings of content from a trusted source.
 type (
 	// CSS encapsulates known safe content that matches any of:
-// (1) The CSS3 stylesheet production, such as `p { color: purple }`.
-// (2) The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
-// (3) CSS3 declaration productions, such as `color: red; margin: 2px`.
-// (4) The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
+//   1. The CSS3 stylesheet production, such as `p { color: purple }`.
+//   2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
+//   3. CSS3 declaration productions, such as `color: red; margin: 2px`.
+//   4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
 	// See http://www.w3.org/TR/css3-syntax/#style
 	CSS string
 
@@ -41,8 +41,8 @@ type (
 	// JSStr encapsulates a sequence of characters meant to be embedded
 	// between quotes in a JavaScript expression.
 	// The string must match a series of StringCharacters:
-// StringCharacter :: SourceCharacter but not `\` or LineTerminator
-//                  | EscapeSequence
+//   StringCharacter :: SourceCharacter but not `\` or LineTerminator
+//                    | EscapeSequence
 	// Note that LineContinuations are not allowed.
 	// JSStr("foo\\nbar") is fine, but JSStr("foo\\\nbar") is not.
 	JSStr string

コアとなるコードの解説

このコミットは、src/pkg/html/template/content.go ファイル内の2つの異なるセクションでドキュメンテーションのインデントを修正しています。

  1. CSS 型のドキュメンテーションコメント:

    • 変更前: 
      // (1) The CSS3 stylesheet production, such as `p { color: purple }`.
// (2) The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
// (3) CSS3 declaration productions, such as `color: red; margin: 2px`.
// (4) The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
      ここでは、箇条書きの各項目が (数字) の形式で始まり、その後のテキストが ( の位置からインデントされていました。これは、Goのドキュメンテーションの一般的なスタイルとは異なり、視覚的に読みにくい可能性がありました。
    • 変更後: 
      //   1. The CSS3 stylesheet production, such as `p { color: purple }`.
//   2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
//   3. CSS3 declaration productions, such as `color: red; margin: 2px`.
//   4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
      変更後では、箇条書きの形式が 数字. に変更され、その後に2つのスペースが追加されています。これにより、各項目のテキストがより深くインデントされ、箇条書きの構造がより明確になりました。これはGoのドキュメンテーションにおける推奨される箇条書きのスタイルに合致しています。

  2. JSStr 型のドキュメンテーションコメント:

    • 変更前: 
      // StringCharacter :: SourceCharacter but not `\` or LineTerminator
//                  | EscapeSequence
      ここでは、StringCharacter の定義が2行にわたって記述されており、2行目の | EscapeSequence が1行目の StringCharacter と同じインデントレベルで始まっていました。これは、EscapeSequence が StringCharacter の代替定義であることを示すには、インデントが不十分でした。
    • 変更後: 
      //   StringCharacter :: SourceCharacter but not `\` or LineTerminator
//                    | EscapeSequence
      変更後では、StringCharacter の行の前に2つのスペースが追加され、さらに | EscapeSequence の行の前に4つのスペースが追加されています。これにより、StringCharacter の定義がより深くインデントされ、| EscapeSequence がその定義の一部として適切にインデントされるようになりました。これは、視覚的に階層構造を明確にし、ドキュメンテーションの意図をより正確に伝えるのに役立ちます。

これらの変更は、コードの動作には影響を与えず、純粋にドキュメンテーションの書式と可読性を改善するためのものです。

関連リンク

参考にした情報源リンク

  • Go言語の公式ドキュメンテーション
  • W3C CSS Working Group の仕様書
  • ECMA International の ECMAScript 仕様書
  • Gitの差分表示に関する一般的な知識
  • Go言語のコードレビュー慣習に関する一般的な知識 (例: R= はレビュアー、CC= はカーボンコピーの対象を示す)
  • GoのIssueトラッカー (golang.org/cl/5437061 はGoのコードレビューシステムGerritのチェンジリストへのリンクです)
  • GitHubのコミット表示機能# [インデックス 10503] ファイルの概要

このコミットは、Go言語の標準ライブラリ html/template パッケージ内の content.go ファイルにおけるドキュメンテーションのインデント（字下げ）を修正するものです。具体的には、CSSおよびJavaScriptの安全なコンテンツ型に関するコメントの箇条書きの書式が調整されています。

コミット

  • コミットハッシュ: 38c082f69e08d7dbb56392b54a546801224ee239
  • Author: Andrew Gerrand adg@golang.org
  • Date: Fri Nov 25 13:32:44 2011 +1100

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

https://github.com/golang/go/commit/38c082f69e08d7dbb56392b54a546801224ee239

元コミット内容

html/template: fix documentation indent

R=nigeltao
CC=golang-dev
https://golang.org/cl/5437061

変更の背景

このコミットの背景は、Go言語の html/template パッケージのドキュメンテーションの可読性と一貫性を向上させることにあります。Goのコードベースでは、コメントやドキュメンテーションの書式に関する特定のガイドラインや慣習が存在します。このコミットは、html/template/content.go 内の CSS および JSStr 型の定義に関するコメントにおいて、箇条書きのインデントが他のドキュメンテーションと異なっていたり、視覚的に読みにくかったりした点を修正することを目的としています。

特に、箇条書きの項目が数字で始まる場合、その数字の後に続くテキストのインデントが適切でないと、リストの構造が分かりにくくなることがあります。この変更は、ドキュメンテーションの整形を改善し、開発者がコードをより容易に理解できるようにするための、小さな品質改善の一環です。

前提知識の解説

このコミットを理解するためには、以下の前提知識があると役立ちます。

  1. Go言語の html/template パッケージ:

    • html/template パッケージは、Go言語でHTML出力を生成する際に、クロスサイトスクリプティング（XSS）などのセキュリティ脆弱性を自動的に防止するための機能を提供するものです。
    • このパッケージは、テンプレートエンジンとして機能し、ユーザーが提供するデータとテンプレートを組み合わせて最終的なHTMLを生成します。
    • 特に重要なのは、template.HTML, template.CSS, template.JS, template.URL, template.JSStr といった「コンテキストに応じたエスケープ」を行うための特殊な型です。これらの型は、その値が特定のコンテキスト（例: HTML属性、CSSスタイル、JavaScriptコード）において安全であるとマークするために使用されます。これにより、悪意のある入力が意図しないコードとして実行されることを防ぎます。
    • template.CSS はCSSとして安全な文字列を、template.JSStr はJavaScriptの文字列リテラルとして安全な文字列を表します。

  2. CSS3 (Cascading Style Sheets Level 3):

    • ウェブページのスタイルを定義するための言語です。
    • CSS3 stylesheet production はCSS全体の構造を指し、CSS3 rule production はセレクタと宣言ブロックからなる個々のCSSルール（例: p { color: blue; }）を指します。
    • CSS3 declaration productions はプロパティと値のペア（例: color: red;）を指し、CSS3 value production はプロパティに割り当てられる具体的な値（例: rgba(0, 0, 255, 127)）を指します。
    • html/template の CSS 型は、これらのCSS構文のいずれかに合致する安全なコンテンツをカプセル化することを意図しています。

  3. JavaScriptの文字列リテラル:

    • JavaScriptにおいて、文字列は通常、シングルクォート (') またはダブルクォート (") で囲まれます。
    • StringCharacter は文字列リテラル内で許可される文字を指します。これには、バックスラッシュ (\) や改行文字（LineTerminator）を除くソースコードの文字が含まれます。
    • EscapeSequence は、バックスラッシュに続く特殊文字（例: \n で改行、\" でダブルクォート）をエスケープするためのシーケンスです。
    • LineContinuations は、バックスラッシュの直後に改行が続くことで、文字列リテラルを複数行にわたって記述する構文ですが、JavaScriptの古い仕様や特定のコンテキストでは許可されない場合があります。html/template の JSStr 型は、このような LineContinuations を含まない、安全なJavaScript文字列リテラルをカプセル化することを意図しています。

技術的詳細

このコミットは、src/pkg/html/template/content.go ファイル内のコメントの書式設定に関するものです。具体的には、CSS 型と JSStr 型のドキュメンテーションコメントにおける箇条書きのインデントが修正されています。

変更前は、箇条書きの各項目が数字と括弧 (1) の形式で始まり、その後に続くテキストが数字の開始位置からインデントされていました。しかし、これはGoのドキュメンテーションの一般的な慣習や、視覚的な読みやすさの点で最適ではありませんでした。

変更後は、箇条書きの項目が数字とピリオド 1. の形式で始まり、その後に続くテキストが数字の開始位置ではなく、数字とピリオドの後のスペースから適切にインデントされるように修正されています。これにより、箇条書きの構造がより明確になり、各項目が独立した情報として認識しやすくなります。

また、JSStr 型のドキュメンテーションでは、StringCharacter と EscapeSequence の説明部分のインデントも調整されています。変更前は、これらの説明が親の箇条書き項目と同じレベルでインデントされていましたが、変更後は、より深いレベルでインデントされ、親項目に対する補足説明であることが視覚的に分かりやすくなっています。

この変更は、コードの機能的な振る舞いには一切影響を与えません。純粋にドキュメンテーションの品質と可読性を向上させるためのものです。Go言語のプロジェクトでは、コードだけでなく、ドキュメンテーションの品質も非常に重視されており、このような細かな修正もコードベース全体の保守性と理解度を高める上で重要とされています。

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

diff --git a/src/pkg/html/template/content.go b/src/pkg/html/template/content.go
index 3fb15a6e93..4de7ccde91 100644
--- a/src/pkg/html/template/content.go
+++ b/src/pkg/html/template/content.go
@@ -12,10 +12,10 @@ import (
 // Strings of content from a trusted source.
 type (
 	// CSS encapsulates known safe content that matches any of:
-// (1) The CSS3 stylesheet production, such as `p { color: purple }`.
-// (2) The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
-// (3) CSS3 declaration productions, such as `color: red; margin: 2px`.
-// (4) The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
+//   1. The CSS3 stylesheet production, such as `p { color: purple }`.
+//   2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
+//   3. CSS3 declaration productions, such as `color: red; margin: 2px`.
+//   4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
 	// See http://www.w3.org/TR/css3-syntax/#style
 	CSS string
 
@@ -41,8 +41,8 @@ type (
 	// JSStr encapsulates a sequence of characters meant to be embedded
 	// between quotes in a JavaScript expression.
 	// The string must match a series of StringCharacters:
-// StringCharacter :: SourceCharacter but not `\` or LineTerminator
-//                  | EscapeSequence
+//   StringCharacter :: SourceCharacter but not `\` or LineTerminator
+//                    | EscapeSequence
 	// Note that LineContinuations are not allowed.
 	// JSStr("foo\\nbar") is fine, but JSStr("foo\\\nbar") is not.
 	JSStr string

コアとなるコードの解説

このコミットは、src/pkg/html/template/content.go ファイル内の2つの異なるセクションでドキュメンテーションのインデントを修正しています。

  1. CSS 型のドキュメンテーションコメント:

    • 変更前: 
      // (1) The CSS3 stylesheet production, such as `p { color: purple }`.
// (2) The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
// (3) CSS3 declaration productions, such as `color: red; margin: 2px`.
// (4) The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
      ここでは、箇条書きの各項目が (数字) の形式で始まり、その後のテキストが ( の位置からインデントされていました。これは、Goのドキュメンテーションの一般的なスタイルとは異なり、視覚的に読みにくい可能性がありました。
    • 変更後: 
      //   1. The CSS3 stylesheet production, such as `p { color: purple }`.
//   2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
//   3. CSS3 declaration productions, such as `color: red; margin: 2px`.
//   4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
      変更後では、箇条書きの形式が 数字. に変更され、その後に2つのスペースが追加されています。これにより、各項目のテキストがより深くインデントされ、箇条書きの構造がより明確になりました。これはGoのドキュメンテーションにおける推奨される箇条書きのスタイルに合致しています。

  2. JSStr 型のドキュメンテーションコメント:

    • 変更前: 
      // StringCharacter :: SourceCharacter but not `\` or LineTerminator
//                  | EscapeSequence
      ここでは、StringCharacter の定義が2行にわたって記述されており、2行目の | EscapeSequence が1行目の StringCharacter と同じインデントレベルで始まっていました。これは、EscapeCharacter が StringCharacter の代替定義であることを示すには、インデントが不十分でした。
    • 変更後: 
      //   StringCharacter :: SourceCharacter but not `\` or LineTerminator
//                    | EscapeSequence
      変更後では、StringCharacter の行の前に2つのスペースが追加され、さらに | EscapeSequence の行の前に4つのスペースが追加されています。これにより、StringCharacter の定義がより深くインデントされ、| EscapeSequence がその定義の一部として適切にインデントされるようになりました。これは、視覚的に階層構造を明確にし、ドキュメンテーションの意図をより正確に伝えるのに役立ちます。

これらの変更は、コードの動作には影響を与えず、純粋にドキュメンテーションの書式と可読性を改善するためのものです。

関連リンク

参考にした情報源リンク

  • Go言語の公式ドキュメンテーション
  • W3C CSS Working Group の仕様書
  • ECMA International の ECMAScript 仕様書
  • Gitの差分表示に関する一般的な知識
  • Go言語のコードレビュー慣習に関する一般的な知識 (例: R= はレビュアー、CC= はカーボンコピーの対象を示す)
  • GoのIssueトラッカー (golang.org/cl/5437061 はGoのコードレビューシステムGerritのチェンジリストへのリンクです)
  • GitHubのコミット表示機能