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

コミット

cb2f6cb05d205a6b55ac1a4055a66de4178e3d53

作成者: Russ Cox rsc@golang.org
日付: 2011年10月18日 16:23:35 (UTC-4)
コミットメッセージ: godoc: generate package toc in template, not in JavaScript

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

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

元コミット内容

godoc: generate package toc in template, not in JavaScript

1. Generate TOC for package pages using template,
instead of using JavaScript magic.  This makes the
pages generated by godoc -html easier to export
to other systems.

2. Make TOC one column.  It's hard to do two columns
portably without invoking JavaScript.

3. Since the TOC is only one column, show full type
signatures for functions and methods.  Many times
that's all you need to see anyway.

4. Name the section after the TOC "Overview".
Naming it something is important, to set it off
from the TOC and so that there's a quick link to
it in the TOC.

For now, some illustrative examples:

http://swtch.com:6060/pkg/io/
http://swtch.com:6060/pkg/strings/
http://swtch.com:6060/pkg/tabwriter/
http://swtch.com:6060/pkg/unicode/

Fixes #1982.

R=gri, bradfitz, r
CC=golang-dev
https://golang.org/cl/5303044

変更の背景

2011年のGo言語は、1.0リリース（2012年3月）に向けて重要な開発段階にありました。godocツールは、Go言語のドキュメント生成システムの核心部分として設計されていましたが、従来のJavaScriptベースのTOC（目次）生成には以下の問題がありました：

移植性の問題: JavaScriptに依存することで、godocで生成されたHTMLページを他のシステムにエクスポートすることが困難でした
レイアウトの制約: 2カラムレイアウトを実現するためにJavaScriptが必要で、ポータブルな実装が困難でした
コンテンツの可読性: JavaScript処理により、関数やメソッドの完全な型シグネチャが見えにくくなっていました

このコミットは、Issue #1982を解決することを目的とし、godocの生成するドキュメントをよりアクセシブルで移植可能なものにしようとした重要な改良でした。

パッケージの概要（Overview）
定数（Constants）
変数（Variables）
関数（Functions）
型（Types）とそのメソッド
バグ情報（Bugs）

技術的詳細

変更されたファイル

doc/godocs.js: JavaScript側のTOC生成ロジックを無効化
lib/godoc/package.html: HTMLテンプレートにTOC生成ロジックを追加

function godocs_generateTOC() {
+  if (document.getElementById('manual-nav')) { return; }
   var navbar = document.getElementById('nav');
   if (!navbar) { return; }

この変更により、manual-navというIDの要素が存在する場合、JavaScript側のTOC生成が無効化されます。

2. HTMLテンプレートの大幅な変更（lib/godoc/package.html）

TOC生成部分の追加

<!-- Table of contents; must be named manual-nav to turn off auto nav. -->
<div id="manual-nav">
{{with .PDoc}}
	<dl>
	<dd><a href="#Overview">Overview</a></dd>
	{{if .Consts}}
		<dd><a href="#Constants">Constants</a></dd>
	{{end}}
	{{if .Vars}}
		<dd><a href="#Variables">Variables</a></dd>
	{{end}}
	{{range .Funcs}}
		{{$name_html := html .Name}}
		<dd><a href="#{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
	{{end}}
	{{range .Types}}
		{{$tname := printf "%s" .Type.Name}}
		{{$tname_html := node_html .Type.Name $.FSet}}
		<dd><a href="#{{$tname_html}}">type {{$tname_html}}</a></dd>
		{{range .Factories}}
			{{$name_html := html .Name}}
			<dd>&nbsp; &nbsp; <a href="#{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
		{{end}}
		{{range .Methods}}
			{{$name_html := html .Name}}
			<dd>&nbsp; &nbsp; <a href="#{{$tname_html}}.{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
		{{end}}
	{{end}}
	{{if .Bugs}}
		<dd><a href="#Bugs">Bugs</a></dd>
	{{end}}
	</dl>
{{end}}
</div>

Overviewセクションの追加

{{with .PDoc}}
+	<h2 id="Overview">Overview</h2>
	<!-- PackageName is printed as title by the top-level template -->

コアとなるコードの解説

テンプレート構文の活用

Goのテンプレート構文を活用して、動的なTOC生成を実現しています：

{{with .PDoc}}...{{end}}: パッケージドキュメントが存在する場合のみ処理
{{if .Consts}}...{{end}}: 定数が存在する場合のみ表示
{{range .Funcs}}...{{end}}: 関数一覧を繰り返し処理
{{$name_html := html .Name}}: 変数の定義とHTMLエスケープ
{{node_html .Decl $.FSet}}: ASTノードからHTMLを生成

comemo

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

コミット

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

元コミット内容

変更の背景

前提知識の解説

godocツール

Go言語のテンプレートシステム

TOC（目次）の生成方式

Go言語のドキュメント構造

技術的詳細

変更されたファイル

主要な技術的改善点

1. テンプレートベースのTOC生成

2. 単一カラムレイアウト

3. 完全な型シグネチャの表示

4. "Overview"セクションの導入

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

1. JavaScript側の変更（doc/godocs.js:49）

2. HTMLテンプレートの大幅な変更（lib/godoc/package.html）

TOC生成部分の追加

Overviewセクションの追加

コアとなるコードの解説

テンプレート構文の活用

セマンティックHTML構造

型安全性の確保

関連リンク

参考にした情報源リンク

Keyboard shortcuts

comemo