Show page source of YukiDocXML/仕様 #25658

>[Yuki]>[YukiDoc]

== YukiDoc XML 仕様 ==

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

{{{ comment
[[PageOutline]]
}}}
[[PageOutline(start=2, depth=3, type=unordered)]]

== 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である事を示します。[[BR]]
このタグの配下に存在しうるタグは'''(YukiDocXMLとしては)'''以下の通りです。
 * YukiDoc (1)
[[BR]]


=== YukiDoc タグ ===
1個存在するタグで、YukiDocXMLである事を示します。[[BR]]
このタグの配下に存在しうるタグは以下の通りです。
 * Include (0..*)
 * Namespace (0..*)
[[BR]]


=== Include タグ ===
0個以上存在するタグで、他のYukiDocXMLを取り込みます。
||属性名||値の範囲||意味||例||
||path||文字列||取り込むYukiDocXMLのパス||YukiDoc/sf.jp.neptune.std/YukiStd.xml||
このタグの配下に存在しうるタグはありません。
[[BR]]


=== Namespace タグ ===
0個以上存在するタグで、名前空間を表現します。
||属性名||値の範囲||意味||例||
||namespace||文字列||名前空間||sf.jp.neptune.plugin.std||
このタグの配下に存在しうるタグは以下の通りです。
 * Multilingual (0..*)
 * Description (0..*)
 * ClassCategories (0..1)
[[BR]]


=== ClassCategories タグ ===
0または1個存在するタグで、ClassCagetoryタグのまとまりを示します。[[BR]]
このタグの配下に存在しうるタグは以下の通りです。
 * ClassCagetory (0..*)
[[BR]]


=== ClassCagetory タグ ===
0個以上存在するタグで、クラスのカテゴリーを表現します。
||属性名||値の範囲||意味||例||
||name||文字列||クラスカテゴリーの英名||2D Graphics||
このタグの配下に存在しうるタグは以下の通りです。
 * Multilingual (0..*)
 * Description (0..*)
 * Classes (0..1)
[[BR]]


=== Multilingual タグ ===
0個以上存在するタグで、言語固有の名前を表現します。
||属性名||値の範囲||意味||例||
||langage||日本語:jp[[BR]]英語:en[[BR]] :[[BR]] :||言語名||jp||
||テキスト||文字列||その言語固有の名前||2D グラフィックス||
このタグの配下に存在しうるタグはありません。
[[BR]]


=== Description タグ ===
0個以上存在するタグで、言語固有の説明を表現します。
||属性名||値の範囲||意味||例||
||langage||日本語:jp[[BR]]英語:en[[BR]] :[[BR]] :||言語名||jp||
||テキスト||文字列||その言語固有の説明||このクラスはxxxのためのクラスです。||
このタグの配下に存在しうるタグはありません。
[[BR]]


=== Classes タグ ===
0または1個存在するタグで、Classタグのまとまりを示します。[[BR]]
このタグの配下に存在しうるタグは以下の通りです。
 * Class(0..*)
[[BR]]


=== Class タグ ===
0個以上存在するタグで、クラスの一つを表現します。
||属性名||値の範囲||意味||例||
||name||文字列||クラスの英名||Layer||
なお、name属性において、ユーザに見せない[YukiDoc/詳細#システムクラス システムクラス]の場合には先頭に「$」を付加します。

このタグの配下に存在しうるタグは以下の通りです。
 * Multilingual (0..*)
 * Description (0..*)
 * Inherits (0..1)
 * Handlers (0..1)
 * Methods (0..1)
[[BR]]


=== Handlers タグ ===
0または1個存在するタグで、Handlerタグのまとまりを示します。[[BR]]
このタグの配下に存在しうるタグは以下の通りです。
 * Inherits (0..1)
 * Handler (0..*)
[[BR]]


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


=== Inherit タグ ===
0個以上存在するタグで、継承するアイテムを表現します。
||属性名||値の範囲||意味||例||
||テキスト||文字列||継承元のパッケージ名やクラス名等[[BR]](その親が何であるかにより異なる)||sf.jp.neptune.plugin.std::$Common:ClickableObject||
このタグの配下に存在しうるタグはありません。
[[BR]]


=== Handler タグ ===
0個以上存在するタグで、そのクラスが持つハンドラの一つを表現します。
||属性名||値の範囲||意味||例||
||name||文字列||ハンドラの英名||OnMouseClick||
このタグの配下に存在しうるタグは以下の通りです。
 * Multilingual (0..*)
 * Description (0..*)
[[BR]]


=== Methods タグ ===
0または1個存在するタグで、メソッドがある場合にMethodタグのまとまりを示します。[[BR]]
このタグの配下に存在しうるタグは以下の通りです。
 * Inherits (0..1)
 * Method (0..*)
[[BR]]


=== Method タグ ===
0個以上存在するタグで、そのクラスが持つメソッドの一つを表現します。
||属性名||値の範囲||意味||例||
||name||文字列||メソッドの英名||FadeIn||
このタグの配下に存在しうるタグは以下の通りです。
 * Multilingual (0..*)
 * Description (0..*)
 * Param (0..*)
 * Return (0..1)
[[BR]]


=== Param タグ ===
0個以上存在するタグで、そのメソッドの引数の一つを表現します。
||属性名||値の範囲||意味||例||
||name||文字列||引数の英名||FadeTime||
||type||int,string,またはクラス名||引数の型名||int||
このタグの配下に存在しうるタグは以下の通りです。
 * Multilingual (0..*)
 * Description (0..*)
[[BR]]


=== Return タグ ===
0または1個存在するタグで、そのメソッドの復帰値を表現します。
||属性名||値の範囲||意味||例||
||type||int,string,またはクラス名||復帰値の型名||int||
このタグの配下に存在しうるタグは以下の通りです。
 * Multilingual (0..*)
 * Description (0..*)
[[BR]]


=== Return タグ ===
0または1個存在するタグで、そのメソッドの性能指標を表現します。[[BR]]
このタグの配下に存在しうるタグは以下の通りです。
 * Time (0..1)
 * Memory (0..1)
[[BR]]


=== Time タグ ===
0または1個存在するタグで、そのメソッドの時間性能指標を表現します。[[BR]]
このタグの配下に存在しうるタグは以下の通りです。
 * Max (0..1)
 * Min (0..1)
 * Ave (0..1)
この値が大きければ大きいほど、処理に時間が掛かる事を意味します。

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

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


=== Memory タグ ===
0または1個存在するタグで、そのメソッドのメモリ使用量指標を表現します。[[BR]]
このタグの配下に存在しうるタグは以下の通りです。
 * Max (0..1)
 * Min (0..1)
 * Ave (0..1)
それぞれのタグでのメモリ使用量単位は「KB(キロバイト)」です。
[[BR]]


=== Max/Min/Ave タグ ===
0または1個存在するタグで、それぞれ指標の最大値、最小値、平均値を表現します。[[BR]]
最大値、最小値、平均値は、パラメータとして指定可能な範囲の最大値、最小値、及び標準的な
パラメータ指定時の平均値より算出します。
{{{ comment
実行時間指標(Time)の測定方法は以下の通りです。

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


== 継承 ==

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

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

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



== クラス図による表現 ==

[[Thumb(YukiDocXmlUml.png)]]


== サンプル ==

[[LinkAttach(NeptuneLibReference.xml , caption=NeptuneLibReference.xml )]]