kagamihogeの日記

kagamihogeの日記です。

JEP 221: Simplified Doclet APIをテキトーに訳した

JEP テキトー翻訳 Java

http://openjdk.java.net/jeps/221 をテキトーに訳した。

JEP 221: Simplified Doclet API

Author   Jonathan Gibbons
Owner   Kumar Srinivasan
Created 2014/05/09 01:45
Updated 2014/10/31 23:38
Type    Feature
Status  Candidate
Component   tools / javadoc(tool)
Scope   Implementation
Discussion  javadoc dash dev at openjdk dot java dot net
Effort  M
Duration    M
Priority    3
Reviewed by Brian Goetz, Jonathan Gibbons
Endorsed by Brian Goetz
Release 9
Issue   8042809
Depends 8035473: [javadoc] Revamp the existing Doclet APIs
    8055509: [javadoc] convert all Tags to DocTree
    8055510: [javadoc] convert all doc Position to Positions
    8055511: [javadoc] Migrate new sources to the main repository
    8055508: [javadoc] convert all javadoc pages to Element
Relates to  8035473: [javadoc] Revamp the existing Doclet APIs

Summary

改善した機能を持つ新規APIを活用するシンプルな設計にDoclet APIを置き換え、そのAPIを使用するように標準docletをアップデートします。

Goals

  • 古くなったAPIのメンテナンス負荷を削減する。
  • Java SE 6で導入されたjavax.lang.modelやstandard language-model APIを使用して、カスタム言語モデルAPI(custom language-model API)の使用を廃止する。
  • JDK 8で導入されたcom.sun.source.doctreeやDocTree APIを使用して、javadocコメント分析用の貧弱なサポートを廃止する。
  • 適切な新しいインターフェース型で、"テンプレートクラス"com.sun.javadoc.Docletの使用箇所を置き換える。

Non-Goals

パフォーマンス改善は目的では無いですが、結果的に、javadocツールと標準docletのパフォーマンスは改善される、と予測されています。

Motivation

現在のAPIには以下のような対処すべき問題があります。

  • docletを定義するAPIは、テンプレートクラスcom.sun.javadoc.Docletが例示するstaticメソッドといくつかのメソッドを実装する、単なるクラスです。staticメソッドの使用はとりわけ問題になりやすく、その理由はメソッド間のデータ共有にstaticメンバの使用を要求されるからです。このことはコンカレントな使用およびテストの両方にとってマイナス要素です。
  • 現行APIは自前の言語モデルAPIを提供していますが、多数の制限（例：配列が十分にモデル化されていない）が存在し、また、APIシグネチャに影響を及ぼす方法（例：ジェネリクス、type annotations, default methods）でJava言語を改良する際の重荷となっています。
  • 現行APIはJavadocコメント分析を提供しており、これは最低限かつ仕様が不完全な(incompletely-specified)ものです。このことは、コメントの内容を処理したいdocletに対し、極めて重い負荷となっています。また、コメント内に構造を持つソースファイル内の位置を取得するAPIをサポートしていません。これにより、診断ツールなどがレポートすべき正確な位置情報を提供することが実質的に不可能となっています。
  • コメント分析用の貧弱なAPIは、同じく貧弱で非効率な実装で構成されており、コメント内の構造を分割するのにsubstring matchingを多用しています。

Description

Doclet APIをLanguage Model APIとDocTree APIを使用して再構築します。他APIを活用するための"umbrella API"はそのまま残される予定です*1。

javadocツールは新しいAPIで書かれたdocletを解するようにアップデートが必要です。我々は移行期間中は既存のAPIをサポートする考えですが、恐らく、旧APIを凍結し、移行期間中に導入された新しい言語機能をサポートするようなアップデートを行わないと思われます。

標準docletを新しいAPIに従うアップデートが必要で、これは本プロジェクトにおける最も主要な作業となります。大部分は、古いイディオムを新しいものに変換する作業になると思われます。

標準docletはTaglet APIとして知られるセカンダリ・プラグインAPIをサポートします。Tagletsは、Javadocコメント内で使用可能なカスタムタグをユーザが定義し、生成されるドキュメント内でそうしたタグがどのように出現すべきかを指定するための、機能を提供します。歴史的経緯により、Taglet APIは既に二つのバージョンが存在し、一つはpublicなもので、もう一つはinternalです。

publicバージョンは既存APIを使用しており、これは本提案の一部によって廃止される見通しなため、それに応じてAPIのアップデートが必要です。

Testing

新しいユースケース用のテストを開発する必要があります。

*1:What remains will be an "umbrella API" to leverage those other APIs.が原文。What remains～の訳がちょっと自身が無い……