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

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

このコミットは、Go言語の公式ドキュメントの一部である「C? Go? Cgo!」という記事のフォーマットを更新するものです。具体的には、記事内のコードスニペットや技術用語の表示を改善し、より読みやすく、視覚的に明確にするための変更が含まれています。また、記事内で参照されているサンプルコードの取り込み方法も調整されています。

コミット

commit d05b3869286a48afbc228992b314f0bf817afc48
Author: Shenghou Ma <minux.ma@gmail.com>
Date:   Mon Mar 19 22:54:06 2012 +0800

    doc: update format for "C? Go? Cgo!" article
    
    R=adg
    CC=golang-dev
    https://golang.org/cl/5841050
---
 doc/articles/c_go_cgo.html | 59 +++++++++++++++++++++++-----------------------
 doc/progs/cgo1.go          |  2 --
 2 files changed, 30 insertions(+), 31 deletions(-)

diff --git a/doc/articles/c_go_cgo.html b/doc/articles/c_go_cgo.html
index 5244021972..1709f06d2a 100644
--- a/doc/articles/c_go_cgo.html
+++ b/doc/articles/c_go_cgo.html
@@ -22,24 +22,24 @@ Let’s look at what\'s happening here, starting with the import statement.\n </p>\n \n <p>\n-The rand package imports \"C\", but you\'ll find there\'s no such package in\n-the standard Go library. That\'s because <code>C</code> is a\n+The <code>rand</code> package imports <code>\"C\"</code>, but you\'ll find there\'s\n+no such package in the standard Go library. That\'s because <code>C</code> is a\n \"pseudo-package\", a special name interpreted by cgo as a reference to C\'s\n name space.\n </p>\n \n <p>\n-The rand package contains four references to the <code>C</code> package:\n-the calls to <code>C.random</code> and <code>C.srandom</code>, the\n-conversion <code>C.uint(i)</code>, and the import statement.\n+The <code>rand</code> package contains four references to the <code>C</code>\n+package: the calls to <code>C.random</code> and <code>C.srandom</code>, the\n+conversion <code>C.uint(i)</code>, and the <code>import</code> statement.\n </p>\n \n <p>\n-The <code>Random</code> function calls the libc random function and returns\n-the result.  In C, random returns a value of the C type <code>long</code>,\n-which cgo represents as the type <code>C.long</code>. It must be converted\n-to a Go type before it can be used by Go code outside this package, using\n-an ordinary Go type conversion:\n+The <code>Random</code> function calls the standard C library\'s <code>random</code>\n+function and returns the result.  In C, <code>random</code> returns a value of the\n+C type <code>long</code>, which cgo represents as the type <code>C.long</code>.\n+It must be converted to a Go type before it can be used by Go code outside this\n+package, using an ordinary Go type conversion:\n </p>\n \n {{code \"/doc/progs/cgo1.go\" `/func Random/` `/STOP/`}}\n@@ -54,30 +54,30 @@ the type conversion more explicitly:\n <p>\n The <code>Seed</code> function does the reverse, in a way. It takes a\n regular Go <code>int</code>, converts it to the C <code>unsigned int</code>\n-type, and passes it to the C function srandom.\n+type, and passes it to the C function <code>srandom</code>.\n </p>\n \n {{code \"/doc/progs/cgo1.go\" `/func Seed/` `/END/`}}\n \n <p>\n-Note that cgo knows the unsigned int type as C.uint; see the\n-<a href=\"/cmd/cgo\">cgo documentation</a> for a complete list of these\n-numeric type names.\n+Note that cgo knows the <code>unsigned int</code> type as <code>C.uint</code>;\n+see the <a href=\"/cmd/cgo\">cgo documentation</a> for a complete list of\n+these numeric type names.\n </p>\n \n <p>\n The one detail of this example we haven\'t examined yet is the comment\n-above the import statement.\n+above the <code>import</code> statement.\n </p>\n \n-{{code \"/doc/progs/cgo1.go\" `/INCLUDE/` `/STOP/`}}\n+{{code \"/doc/progs/cgo1.go\" `/\\/\\*/` `/STOP/`}}\n \n <p>\n Cgo recognizes this comment and uses it as a header when compiling the C\n parts of the package. In this case it is just a simple include statement,\n but it can be any valid C code. The comment must be immediately before the\n-line that imports \"C\", without any intervening blank lines, just like a\n-documentation comment.\n+line that imports <code>\"C\"</code>, without any intervening blank lines,\n+just like a documentation comment.\n </p>\n \n <p>\n@@ -114,11 +114,11 @@ by calling <code>C.free</code>.\n <p>\n The call to <code>C.CString</code> returns a pointer to the start of the\n char array, so before the function exits we convert it to an\n-<a href=\"/pkg/unsafe/#Pointer\">unsafe.Pointer</a> and release the memory\n-allocation with <code>C.free</code>. A common idiom in cgo programs is to\n-<a href=\"/doc/articles/defer_panic_recover.html\">defer</a> the free\n-immediately after allocating (especially when the code that follows is more\n-complex than a single function call), as in this rewrite of\n+<a href=\"/pkg/unsafe/#Pointer\"><code>unsafe.Pointer</code></a> and release\n+the memory allocation with <code>C.free</code>. A common idiom in cgo programs\n+is to <a href=\"/doc/articles/defer_panic_recover.html\"><code>defer</code></a>\n+the free immediately after allocating (especially when the code that follows\n+is more complex than a single function call), as in this rewrite of\n <code>Print</code>:\n </p>\n \n@@ -129,10 +129,11 @@ complex than a single function call), as in this rewrite of\n </p>\n \n <p>\n-To build cgo packages, just use <a href=\"/cmd/go/#Compile_packages_and_dependencies\">\"go build\"</a> or\n-<a href=\"/cmd/go/#Compile_and_install_packages_and_dependencies\">\"go install\"</a>\n-as usual. The go tool recognizes the special \"C\" import and automatically uses\n-cgo for those files.\n+To build cgo packages, just use <a href=\"/cmd/go/#Compile_packages_and_dependencies\">\"\n+<code>go build</code>\"</a> or\n+<a href=\"/cmd/go/#Compile_and_install_packages_and_dependencies\">\"<code>go install</code>\n+\"</a> as usual. The go tool recognizes the special <code>\"C\"</code> import and automatically\n+uses cgo for those files.\n </p>\n \n <p>\n@@ -141,8 +142,8 @@ cgo for those files.\n \n <p>\n The <a href=\"/cmd/cgo/\">cgo command</a> documentation has more detail about\n-the C pseudo-package and the build process. The cgo examples in the Go tree\n-demonstrate more advanced concepts.\n+the C pseudo-package and the build process. The <a href=\"/misc/cgo/\">cgo examples</a>\n+in the Go tree demonstrate more advanced concepts.\n </p>\n \n <p>\ndiff --git a/doc/progs/cgo1.go b/doc/progs/cgo1.go\nindex 3125cda3d8..b79ee368a4 100644\n--- a/doc/progs/cgo1.go\n+++ b/doc/progs/cgo1.go\n@@ -3,8 +3,6 @@\n // license that can be found in the LICENSE file.\n package rand\n \n-// INCLUDE OMIT\n-\n /*\n #include <stdlib.h>\n */\n```

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

[https://github.com/golang/go/commit/d05b3869286a48afbc228992b314f0bf817afc48](https://github.com/golang/go/commit/d05b3869286a48afbc228992b314f0bf817afc48)

## 元コミット内容

このコミットは、Go言語のドキュメントの一部である「C? Go? Cgo!」という記事のフォーマットを更新することを目的としています。元の記事は、GoプログラムからC言語のコードを呼び出すための`cgo`ツールの使い方を解説するものでした。このコミット以前は、記事内の特定のコード要素や技術用語がプレーンテキストとして表示されており、視認性や可読性の点で改善の余地がありました。また、記事に埋め込まれるサンプルコードの指定方法も、より柔軟なものに変更する必要がありました。

## 変更の背景

この変更の背景には、Go言語の公式ドキュメントの品質向上と、読者体験の改善があります。技術記事において、コードスニペットや専門用語は明確に区別して表示されるべきです。これにより、読者は記事の内容をより迅速に理解し、重要な概念を把握することができます。

具体的には、以下の点が変更の動機と考えられます。

1.  **可読性の向上**: 記事内で言及されるGoのパッケージ名（例: `rand`）、Cの関数名（例: `random`, `srandom`）、Goの型（例: `int`）、Cの型（例: `long`, `unsigned int`）、キーワード（例: `import`, `defer`）、コマンド（例: `go build`）などが、プレーンテキストのままだと他の文章と区別しにくく、読者が混乱する可能性がありました。これらを`<code>`タグで囲むことで、コード要素であることが一目でわかるようになり、可読性が大幅に向上します。
2.  **一貫性の確保**: Goの公式ドキュメント全体で、コード要素や技術用語の表示方法に一貫性を持たせるための取り組みの一環である可能性があります。
3.  **コードブロックの柔軟な取り込み**: 記事内でサンプルコードを埋め込む際に使用される`{{code}}`テンプレートの機能改善も目的の一つです。以前は特定のコメント行（`// INCLUDE OMIT`）をマーカーとして使用していましたが、より汎用的な正規表現（C言語のコメント開始を示す`/*`）でコードブロックの開始位置を指定できるようにすることで、サンプルコードの記述方法に柔軟性を持たせることができます。これにより、記事の執筆者は、サンプルコードの構造をより自由に設計できるようになります。

これらの変更は、読者が「C? Go? Cgo!」記事を通じて`cgo`の概念と使い方をより効果的に学習できるようにするための、細部にわたる配慮の結果と言えます。

## 前提知識の解説

このコミットの変更内容を理解するためには、以下の前提知識が必要です。

1.  **Go言語**: Googleによって開発されたオープンソースのプログラミング言語です。シンプルさ、効率性、並行処理のサポートが特徴です。
2.  **HTML**: Webページの構造を定義するためのマークアップ言語です。特に、`<code>`タグはインラインのコードスニペットや技術用語を表現するために使用されます。
3.  **cgo**: Go言語のツールチェーンの一部であり、GoプログラムからC言語のコードを呼び出したり、C言語のコードからGoの関数を呼び出したりするための機能を提供します。`cgo`を使用することで、既存のCライブラリをGoプロジェクトで再利用したり、パフォーマンスが重要な部分をCで記述したりすることが可能になります。
    *   **`import "C"`**: `cgo`を使用するGoファイルでは、特別な「擬似パッケージ」である`"C"`をインポートします。このインポート文は、Goコンパイラに対して、このファイルが`cgo`によって処理される必要があることを示します。
    *   **`C`擬似パッケージ**: `import "C"`によって導入される`C`擬似パッケージは、C言語の名前空間への参照として機能します。Goコード内で`C.関数名`や`C.型名`のように記述することで、C言語の関数や型にアクセスできます。
    *   **C言語の型とGo言語の型の変換**: `cgo`を使用する際には、C言語の型とGo言語の型の間で明示的な変換が必要になることがよくあります。例えば、Cの`long`型はGoでは`C.long`として扱われ、Goの`int`型に変換するには`int(C.long_value)`のように記述します。
    *   **Cgoディレクティブ（Cコメントブロック）**: `import "C"`の直前にあるC言語のコメントブロック（`/* ... */`）は、`cgo`に対する特別なディレクティブとして扱われます。このブロック内には、C言語のヘッダーファイルのインクルード（例: `#include <stdlib.h>`)や、C言語の関数定義などを記述できます。`cgo`は、このコメントブロックの内容をCコンパイラに渡して、Goコードから呼び出されるC関数をコンパイルします。
4.  **Goドキュメントのテンプレートシステム**: Goの公式ドキュメントは、特定のテンプレート構文を使用して構築されています。このコミットで登場する`{{code "ファイルパス" "開始正規表現" "終了正規表現"}}`のような構文は、指定されたファイルから正規表現にマッチする範囲のコードを抽出し、ドキュメントに埋め込むためのものです。

これらの知識があることで、コミットが単なるテキストの変更ではなく、Goのドキュメント生成プロセスと`cgo`の機能に関する深い理解に基づいていることがわかります。

## 技術的詳細

このコミットにおける技術的詳細は、主にHTMLのマークアップとGoドキュメントのテンプレート機能の利用に集約されます。

1.  **`<code>`タグの適用**:
    *   記事内で言及されるGoのパッケージ名、Cの関数名、Go/Cの型名、Goのキーワード、Goコマンドなど、技術的な用語やコード要素に対して、一貫して`<code>`タグが適用されています。
    *   例: `rand` -> `<code>rand</code>`、`"C"` -> `<code>"C"</code>`、`random` -> `<code>random</code>`、`C.uint(i)` -> `<code>C.uint(i)</code>`、`import` -> `<code>import</code>`、`long` -> `<code>long</code>`、`unsigned int` -> `<code>unsigned int</code>`、`unsafe.Pointer` -> `<code>unsafe.Pointer</code>`、`defer` -> `<code>defer</code>`、`go build` -> `<code>go build</code>`、`go install` -> `<code>go install</code>`、`cgo command` -> `<code>cgo command</code>`。
    *   これにより、ブラウザで表示された際にこれらの要素が等幅フォントで表示され、通常の文章と視覚的に区別されるため、技術文書としての可読性が向上します。

2.  **`{{code}}`テンプレートの正規表現変更**:
    *   `doc/articles/c_go_cgo.html`内の以下の行が変更されました。
        *   `-{{code "/doc/progs/cgo1.go" `/INCLUDE/` `/STOP/`}}`
        *   `+{{code "/doc/progs/cgo1.go" `/\\/\\*/` `/STOP/`}}`
    *   これは、`doc/progs/cgo1.go`ファイルからコードブロックを抽出する際の開始マーカーの指定方法を変更したものです。
    *   変更前は、`INCLUDE`という文字列（おそらく`// INCLUDE OMIT`のようなコメント行）を正規表現で探していました。
    *   変更後は、`/\\/\\*/`という正規表現を使用しています。これは、C言語の複数行コメントの開始を示す`/*`という文字列にマッチします。正規表現内で`/`をエスケープするために`\\/`が使用されています。
    *   この変更に伴い、`doc/progs/cgo1.go`からは、以前のマーカーであった`// INCLUDE OMIT`の行が削除されています。これにより、コードブロックの抽出がCコメントの開始位置から行われるようになります。
    *   この変更は、ドキュメント生成システムが、より一般的なC言語のコメント構文をコードブロックの開始点として認識できるようにするためのものです。これにより、サンプルコードの記述において、特定のマーカーコメントを挿入する必要がなくなり、より自然なコード構造を維持できるようになります。

3.  **リンクテキストの変更**:
    *   `unsafe.Pointer`へのリンクテキストが、単なる`unsafe.Pointer`から`<code>unsafe.Pointer</code>`に変更されました。
    *   `defer`へのリンクテキストが、単なる`defer`から`<code>defer</code>`に変更されました。
    *   `go build`と`go install`へのリンクテキストが、単なる`"go build"`と`"go install"`から`"<code>go build</code>"`と`"<code>go install</code>"`に変更されました。
    *   `cgo examples`へのリンクテキストが、単なる`cgo examples`から`<a href="/misc/cgo/">cgo examples</a>`に変更されました。これは、リンク自体は以前から存在していたものの、その表示形式がより明確になったことを示唆しています。

これらの変更は、HTMLのセマンティクスとGoドキュメントのビルドプロセスを深く理解していることを示しており、ドキュメントの品質向上に対する細やかな配慮がなされています。

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

このコミットで変更されたファイルは以下の2つです。

1.  `doc/articles/c_go_cgo.html`: 「C? Go? Cgo!」記事のHTMLソースファイル。
2.  `doc/progs/cgo1.go`: 上記記事で参照されているGoのサンプルコードファイル。

変更の概要は以下の通りです。

*   `doc/articles/c_go_cgo.html`: 30行追加、31行削除。主に既存のテキストに`<code>`タグを追加する変更と、`{{code}}`テンプレートの正規表現の変更。
*   `doc/progs/cgo1.go`: 0行追加、2行削除。記事から参照されるコードブロックの開始マーカーとして使用されていたコメント行の削除。

## コアとなるコードの解説

### `doc/articles/c_go_cgo.html` の変更

このファイルでは、記事の本文中の多くの箇所で、技術用語やコード要素を`<code>`タグで囲む変更が行われています。これにより、これらの要素が等幅フォントで表示され、通常の文章と区別されるようになります。

**例1: パッケージ名、擬似パッケージ名、関数名、型名の強調**

```diff
-The rand package imports "C", but you'll find there's no such package in
-the standard Go library. That's because <code>C</code> is a
+The <code>rand</code> package imports <code>"C"</code>, but you'll find there's
+no such package in the standard Go library. That's because <code>C</code> is a
  • rand -> <code>rand</code>
  • "C" -> <code>"C"</code>
-The rand package contains four references to the <code>C</code> package:
-the calls to <code>C.random</code> and <code>C.srandom</code>, the
-conversion <code>C.uint(i)</code>, and the import statement.
+The <code>rand</code> package contains four references to the <code>C</code>
+package: the calls to <code>C.random</code> and <code>C.srandom</code>, the
+conversion <code>C.uint(i)</code>, and the <code>import</code> statement.
  • C.random -> <code>C.random</code>
  • C.srandom -> <code>C.srandom</code>
  • C.uint(i) -> <code>C.uint(i)</code>
  • import -> <code>import</code>

例2: C言語の関数名と型の強調

-The <code>Random</code> function calls the libc random function and returns
-the result.  In C, random returns a value of the C type <code>long</code>,
-which cgo represents as the type <code>C.long</code>. It must be converted
-to a Go type before it can be used by Go code outside this package, using
-an ordinary Go type conversion:
+The <code>Random</code> function calls the standard C library's <code>random</code>
+function and returns the result.  In C, <code>random</code> returns a value of the
+C type <code>long</code>, which cgo represents as the type <code>C.long</code>.
+It must be converted to a Go type before it can be used by Go code outside this
+package, using an ordinary Go type conversion:
  • random -> <code>random</code>
  • long -> <code>long</code>
  • C.long -> <code>C.long</code>

例3: unsigned intとC.uintの強調

-regular Go <code>int</code>, converts it to the C <code>unsigned int</code>
-type, and passes it to the C function srandom.
+regular Go <code>int</code>, converts it to the C <code>unsigned int</code>
+type, and passes it to the C function <code>srandom</code>.
  • unsigned int -> <code>unsigned int</code>
  • srandom -> <code>srandom</code>
-Note that cgo knows the unsigned int type as C.uint; see the
-<a href="/cmd/cgo">cgo documentation</a> for a complete list of these
-numeric type names.
+Note that cgo knows the <code>unsigned int</code> type as <code>C.uint</code>;
+see the <a href="/cmd/cgo">cgo documentation</a> for a complete list of
+these numeric type names.
  • unsigned int -> <code>unsigned int</code>
  • C.uint -> <code>C.uint</code>

例4: unsafe.Pointerとdeferの強調

-char array, so before the function exits we convert it to an
-<a href="/pkg/unsafe/#Pointer">unsafe.Pointer</a> and release the memory
-allocation with <code>C.free</code>. A common idiom in cgo programs is to
-<a href="/doc/articles/defer_panic_recover.html">defer</a> the free
-immediately after allocating (especially when the code that follows is more
-complex than a single function call), as in this rewrite of
+char array, so before the function exits we convert it to an
+<a href="/pkg/unsafe/#Pointer"><code>unsafe.Pointer</code></a> and release
+the memory allocation with <code>C.free</code>. A common idiom in cgo programs
+is to <a href="/doc/articles/defer_panic_recover.html"><code>defer</code></a>
+the free immediately after allocating (especially when the code that follows
+is more complex than a single function call), as in this rewrite of
  • unsafe.Pointer -> <code>unsafe.Pointer</code> (リンクテキスト内)
  • defer -> <code>defer</code> (リンクテキスト内)

例5: Goコマンドの強調

-To build cgo packages, just use <a href="/cmd/go/#Compile_packages_and_dependencies">"go build"</a> or
-<a href="/cmd/go/#Compile_and_install_packages_and_dependencies">"go install"</a>
-as usual. The go tool recognizes the special "C" import and automatically uses
-cgo for those files.
+To build cgo packages, just use <a href="/cmd/go/#Compile_packages_and_dependencies">"
+<code>go build</code>"</a> or
+<a href="/cmd/go/#Compile_and_install_packages_and_dependencies">"<code>go install</code>
+"</a> as usual. The go tool recognizes the special <code>"C"</code> import and automatically
+uses cgo for those files.
  • "go build" -> "<code>go build</code>" (リンクテキスト内)
  • "go install" -> "<code>go install</code>" (リンクテキスト内)

例6: {{code}}テンプレートの正規表現の変更

-{{code "/doc/progs/cgo1.go" `/INCLUDE/` `/STOP/`}}
+{{code "/doc/progs/cgo1.go" `/\\/\\*/` `/STOP/`}}
  • これは、doc/progs/cgo1.goからコードを抽出する際の開始マーカーの正規表現を、/INCLUDE/から/\\/\\*/（C言語のコメント開始/*にマッチ）に変更したものです。

doc/progs/cgo1.go の変更

このファイルでは、記事の{{code}}テンプレートで以前使用されていたコードブロックの開始マーカーが削除されています。

--- a/doc/progs/cgo1.go
+++ b/doc/progs/cgo1.go
@@ -3,8 +3,6 @@
 // license that can be found in the LICENSE file.\n package rand
 
-// INCLUDE OMIT
-
 /*
 #include <stdlib.h>
 */
  • - // INCLUDE OMIT の行が削除されています。これは、doc/articles/c_go_cgo.htmlの{{code}}テンプレートの正規表現が変更されたため、このマーカーが不要になったことを意味します。

これらの変更は、記事の視覚的な品質と、ドキュメント生成プロセスの柔軟性を向上させるためのものです。

関連リンク

参考にした情報源リンク