YukiDocXML/仕様 - Neptune Wiki - Neptune

＞Yuki＞YukiDoc

YukiDoc XML 仕様

• エンコードはUTF-8固定（複数のエンコードが交じり合う可能性があるため）
• ()は省略可能を意味
• 「：」は複数ある事を意味

Outline

• YukiDoc XML 仕様
• XMLの簡単な構造
• タグ/属性詳細
  • yuki タグ
  • YukiDoc タグ
  • Include タグ
  • Namespace タグ
  • ClassCategories タグ
  • ClassCagetory タグ
  • Multilingual タグ
  • Description タグ
  • Classes タグ
  • Class タグ
  • Handlers タグ
  • Inherits タグ
  • Inherit タグ
  • Handler タグ
  • Methods タグ
  • Method タグ
  • Param タグ
  • Return タグ
  • Return タグ
  • Time タグ
  • Memory タグ
  • Max/Min/Ave タグ
• 継承
• クラス図による表現
• サンプル

XMLの簡単な構造

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<yuki>
  (<YukiDoc>
    (<Namespace namespace="名前空間">
      (<ClassCategories>
        (<ClassCagetory name="カテゴリの英名">
          (<Multilingual langage="言語名">言語固有の名前</Multilingual>
          　：)
          (<Description langage="言語名">言語固有の説明</Description>
          　：)
          
          (<Classes>
            (<Class name="クラス名の英名">
              (<Multilingual langage="言語名">言語固有の名前</Multilingual>
              　：)
              (<Description langage="言語名">言語固有の説明</Description>
              　：)

              (<Handlers>
                (<Inherits>
                  (<Inherit>継承元</Inherit>
                  　：)
                </Inherits>)
                
                (<Handler name="ハンドラの英名">
                  (<Multilingual langage="言語名">言語固有の名前</Multilingual>
                  　：)
                </Handler>)
              </Handlers>)
              
              (<Methods>
                <Method name="メソッドの英名">
                  (<Multilingual langage="言語名">言語固有の名前</Multilingual>
                  　：)
                  (<Description langage="言語名">言語固有の説明</Description>
                  　：)
                  
                  (<Param name="パラメータの英名" type="型名">
                    (<Multilingual langage="言語名">言語固有の名前</Multilingual>
                    　：)
                    (<Description langage="言語名">言語固有の説明</Description>
                    　：)
                  </Param>
                  　：)
                  
                  (<Return type="">コメント
                    (<Multilingual langage="言語名">言語固有の名前</Multilingual>
                    　：)
                    (<Description langage="言語名">言語固有の説明</Description>
                    　：)
                  </Return>)
                  
                  <!-- 性能 -->
                  <Performance>
                    <Time>
                      <Max>20</Max>
                      <Min>20</Min>
                      <Ave>20</Ave>
                    </Time>
                    <Memory>
                      <Max>20</Max>
                      <Min>20</Min>
                      <Ave>20</Ave>
                    </Memory>
                  </Performance>
                </Method>
                　：
              </Methods>
            </Class>
            　：
          </Classes>
        </Cagetory>
        　：
      </ClassCategories>
    </Namespace>
    　：
  </YukiDoc>
</yuki>

タグ/属性詳細

yuki タグ

1個存在するタグで、Yukiに関連するXMLである事を示します。
このタグの配下に存在しうるタグは（YukiDocXMLとしては）以下の通りです。

• YukiDoc (1)

YukiDoc タグ

1個存在するタグで、YukiDocXMLである事を示します。
このタグの配下に存在しうるタグは以下の通りです。

• Include (0..*)
• Namespace (0..*)

Include タグ

0個以上存在するタグで、他のYukiDocXMLを取り込みます。

属性名	値の範囲	意味	例
path	文字列	取り込むYukiDocXMLのパス	YukiDoc/sf.jp.neptune.std/YukiStd.xml

このタグの配下に存在しうるタグはありません。

Namespace タグ

0個以上存在するタグで、名前空間を表現します。

属性名	値の範囲	意味	例
namespace	文字列	名前空間	sf.jp.neptune.plugin.std

このタグの配下に存在しうるタグは以下の通りです。

• Multilingual (0..*)
• Description (0..*)
• ClassCategories (0..1)

ClassCategories タグ

0または1個存在するタグで、ClassCagetoryタグのまとまりを示します。
このタグの配下に存在しうるタグは以下の通りです。

• ClassCagetory (0..*)

ClassCagetory タグ

0個以上存在するタグで、クラスのカテゴリーを表現します。

属性名	値の範囲	意味	例
name	文字列	クラスカテゴリーの英名	2D Graphics

このタグの配下に存在しうるタグは以下の通りです。

• Multilingual (0..*)
• Description (0..*)
• Classes (0..1)

Multilingual タグ

0個以上存在するタグで、言語固有の名前を表現します。

属性名	値の範囲	意味	例
langage	日本語：jp 英語：en 　： 　：	言語名	jp
テキスト	文字列	その言語固有の名前	2D グラフィックス

このタグの配下に存在しうるタグはありません。

Description タグ

0個以上存在するタグで、言語固有の説明を表現します。

属性名	値の範囲	意味	例
langage	日本語：jp 英語：en 　： 　：	言語名	jp
テキスト	文字列	その言語固有の説明	このクラスはｘｘｘのためのクラスです。

このタグの配下に存在しうるタグはありません。

Classes タグ

0または1個存在するタグで、Classタグのまとまりを示します。
このタグの配下に存在しうるタグは以下の通りです。

• Class(0..*)

Class タグ

0個以上存在するタグで、クラスの一つを表現します。

属性名	値の範囲	意味	例
name	文字列	クラスの英名	Layer

なお、name属性において、ユーザに見せないシステムクラスの場合には先頭に「$」を付加します。

このタグの配下に存在しうるタグは以下の通りです。

• Multilingual (0..*)
• Description (0..*)
• Inherits (0..1)
• Handlers (0..1)
• Methods (0..1)

Handlers タグ

0または1個存在するタグで、Handlerタグのまとまりを示します。
このタグの配下に存在しうるタグは以下の通りです。

• Inherits (0..1)
• Handler (0..*)

Inherits タグ

0または1個存在するタグで、継承するものがある場合にInheritタグのまとまりを示します。
このタグの配下に存在しうるタグは以下の通りです。

• Inherit (0..*)

Inherit タグ

0個以上存在するタグで、継承するアイテムを表現します。

属性名	値の範囲	意味	例
テキスト	文字列	継承元のパッケージ名やクラス名等 （その親が何であるかにより異なる）	sf.jp.neptune.plugin.std::$Common:ClickableObject

このタグの配下に存在しうるタグはありません。

Handler タグ

0個以上存在するタグで、そのクラスが持つハンドラの一つを表現します。

属性名	値の範囲	意味	例
name	文字列	ハンドラの英名	OnMouseClick

このタグの配下に存在しうるタグは以下の通りです。

• Multilingual (0..*)
• Description (0..*)

Methods タグ

0または1個存在するタグで、メソッドがある場合にMethodタグのまとまりを示します。
このタグの配下に存在しうるタグは以下の通りです。

• Inherits (0..1)
• Method (0..*)

Method タグ

0個以上存在するタグで、そのクラスが持つメソッドの一つを表現します。

属性名	値の範囲	意味	例
name	文字列	メソッドの英名	FadeIn

このタグの配下に存在しうるタグは以下の通りです。

• Multilingual (0..*)
• Description (0..*)
• Param (0..*)
• Return (0..1)

Param タグ

0個以上存在するタグで、そのメソッドの引数の一つを表現します。

属性名	値の範囲	意味	例
name	文字列	引数の英名	FadeTime
type	int,string,またはクラス名	引数の型名	int

このタグの配下に存在しうるタグは以下の通りです。

• Multilingual (0..*)
• Description (0..*)

Return タグ

0または1個存在するタグで、そのメソッドの復帰値を表現します。

属性名	値の範囲	意味	例
type	int,string,またはクラス名	復帰値の型名	int

このタグの配下に存在しうるタグは以下の通りです。

• Multilingual (0..*)
• Description (0..*)

Return タグ

0または1個存在するタグで、そのメソッドの性能指標を表現します。
このタグの配下に存在しうるタグは以下の通りです。

• Time (0..1)
• Memory (0..1)

Time タグ

0または1個存在するタグで、そのメソッドの時間性能指標を表現します。
このタグの配下に存在しうるタグは以下の通りです。

• Max (0..1)
• Min (0..1)
• Ave (0..1)

この値が大きければ大きいほど、処理に時間が掛かる事を意味します。

値は単純な時間ではなく、以下の手法により測定された指標値です。

• とある指標命令をn回実行した際の時間をXとする。
• 同測定環境にて、当該対象メソッドを実行した際の最大、最小、平均時間をYとする。
• Y / X * 100 の値を指標値とする。

Memory タグ

0または1個存在するタグで、そのメソッドのメモリ使用量指標を表現します。
このタグの配下に存在しうるタグは以下の通りです。

• Max (0..1)
• Min (0..1)
• Ave (0..1)

それぞれのタグでのメモリ使用量単位は「KB（キロバイト）」です。

Max/Min/Ave タグ

0または1個存在するタグで、それぞれ指標の最大値、最小値、平均値を表現します。
最大値、最小値、平均値は、パラメータとして指定可能な範囲の最大値、最小値、及び標準的な パラメータ指定時の平均値より算出します。

継承

全く同じメソッドや、ハンドラ等がある場合、これをコピペする事は冗長である。
これを回避するため、YukiDoc XMLでは継承構造を提供する。

Inherits タグを許可するタグ配下にて、Inherits タグを記述し、他のメソッド名やハンドラ名、 クラス名等を記述する事によりこれを継承出来る。むしろ、多くのメソッドやハンドラでは この継承を積極的に利用すべきであり、それぞれで好き勝手にメソッドやハンドラの仕様を実装していくのは インターフェースの一貫性を失い、非常に使い勝手の悪いものとなる。

特にYukiでは「どのパッケージのインターフェースであるか」と言う情報は秘匿されるため、 どのクラスもメソッドも、ユーザからは同一視される。そのためインターフェースを極力一貫させることは Yukiにとって非常に重要な事である。

クラス図による表現

サンプル

NeptuneLibReference.xml