svnno****@sourc*****
svnno****@sourc*****
2009年 4月 16日 (木) 00:51:04 JST
Revision: 3295
http://svn.sourceforge.jp/view?root=jiemamy&view=rev&rev=3295
Author: daisuke_m
Date: 2009-04-16 00:51:04 +0900 (Thu, 16 Apr 2009)
Log Message:
-----------
ドキュメント追加。
Modified Paths:
--------------
metis/documents/trunk/src/docbook/api-quickstart/api-quickstart.xml
-------------- next part --------------
Modified: metis/documents/trunk/src/docbook/api-quickstart/api-quickstart.xml
===================================================================
--- metis/documents/trunk/src/docbook/api-quickstart/api-quickstart.xml 2009-04-15 13:50:39 UTC (rev 3294)
+++ metis/documents/trunk/src/docbook/api-quickstart/api-quickstart.xml 2009-04-15 15:51:04 UTC (rev 3295)
@@ -150,6 +150,46 @@
<title>インポート・エクスポート</title>
<para>作成したモデルは、インポータ・エクスポータを使用して、(TODO)</para>
</chapter>
+
+ <chapter id="api">
+ <title>APIについて</title>
+ <para>以上の通り、Jiemamyはモデルの操作APIを公開し、作ったモデルを自由に扱うことができます。</para>
+ <para>しかし、リリースして間もないこともあり、未成熟であるのも事実です。今後のバージョンアップにより、バグ修正やAPIの修正・拡張を行っていく
+ことになると思いますが、そのポリシーを説明します。
+ </para>
+ <para>Jiemamyの仕様コンポーネント(spec)のバージョンは、"major.minor[-SNAPSHOT]"形式です。
+majorは大なアーキテクチャの変更があった際に繰り上げ、minorは、仕様に変更（つまり、specに対するあらゆる変更）があった際に繰上げます。
+APIの追加は随時行っていきます。そして、APIの廃止は @Deprecated アノテーションで対処し、時期を見て実際に削除します。
+ ＠ Deprecatedから実際の削除までの期間は、v1.0以前は2～3ヶ月、v1.0以降は未定です。（もしかしたらメジャーバージョンアップまで消さない、とするかもしれません。）
+また、API変更について、メソッドのシグネチャが変わる場合は、旧メソッドを @Deprecated とし、新メソッドをオーバーロードする形にします。
+シグネチャの変更を伴わない変更（挙動の変更＝Javadocの変更）は、v1.0以前は随時行う。v1.0以降はどうするか検討中です。
+しかし、バージョンアップに伴い、既存のクライアントに影響を出さない事を重要事項として扱っていきます。
+ </para>
+ <para>実装コンポーネントのバージョニングは、"major.minor.release[-SNAPSHOT]"形式です。
+major, minorは、準拠する対象仕様バージョンに合わせ（spec v0.2準拠の場合は、v0.2.x）、仕様に変更がなく実装のみを修正（bug fix等）した場合に、
+releaseを繰り上げます。
+ </para>
+ <para>次に、Jiemamyのバグの基準を示します。</para>
+ <para>バグには「仕様バグ」（Javadoc自体の記述漏れ・不整合など）と「実装バグ」（コードの不整合など）がありえます。
+前者はspecの修正が必要となり、後者は実装の修正を行います。（その時のバージョン番号ポリシーは上記の通り）
+ </para>
+ <para>Jiemamyの開発は、以下のルールを適用しています。</para>
+ <itemizedlist>
+ <listitem><para>Javadocの @throws は RuntimeException についても記述されていなければならない。
+つまり、メソッド呼び出しの結果、Javadocに記述のない例外（RuntimeExceptionを含む）が飛んだら、バグである。
+（これは「飛ぶべきではない例外が飛ぶ」という実装バグの可能性と、「飛ぶべき例外がJavadocに記述されていない」という仕様バグの可能性があります。）
+ </para></listitem>
+ <listitem><para>APIの挙動については全てJavadocに記述されているべきで、Javadocを読めば何が起るか全て把握できるべき。
+「こういうケースではどうなるのだろう？」という疑問が発生する時点で、Javadocの記述漏れとみなす。（ただし、reflectionで強制的にフィールドを書き換えたりした
+場合はどうなるのだろう、等はナシで。） 呼び出しの結果、Javadocに記述されていない動作をするのはバグである。
+（これは「すべきではない動作をする」という実装バグの可能性と、「すべきである動作がJavadocに記述されていない」という仕様バグの可能性があります。）
+ </para></listitem>
+ <listitem><para>JiemamyのAPIは NullPointerException をスローしない。NullPointerExceptionが飛んだらバグである。</para></listitem>
+ </itemizedlist>
+ <para>以上のようなケースに遭遇（まだまだ多いと思います）した際には、最終章に記述してあるメーリングリストにご一報下さい。
+Jiemamyの品質向上にご協力お願いいたします。
+ </para>
+ </chapter>
<xi:include href="../common/chapter_finish.xml" />