NaturalDocsの書き方と、出力結果

ActionScript用のドキュメンテーションツールといえばASDocですが、
前から面白そうだなーと思っていたNaturalDocsがついこの前、最新バージョンが出てみたので使ってみました。

ちょっと使ってみた感じではNaturalDocsなかなか面白いと感じました。
ASDocは使ってないんので比較評価ができなかったので、その辺りFlash使いの人の意見聞いてみたいですねー

●NaturalDocsの出力(エンコードをutf-8にしないと化けます！）
http://funnystep.sakura.ne.jp/sample/NaturalDocs/index.html
●ASDocの出力
http://funnystep.sakura.ne.jp/sample/ASDoc/index.html

●NaturalDocs使い方解説
●１.ダウンロード
http://www.naturaldocs.org/download.html
まずはこのページでzipをゲットします。

●2.Windowsの方はActivePerlを落とす
NaturalDocsはperlで動いているので、
適当なサイトからActivePerlをゲットしてください。

●3.zipフォルダを解凍する。
zipフォルダの内のNaturalDocsが本体です。
これを引数付けてperlで実行するとファイルが作成されます。

●4コンパイル方法
NaturalDocsにパスが通っていれば、以下の方法でドキュメント作成できます。

perl NaturalDocs -i プロジェクトディレクトリ -o FramedHTML 設定ファイルディレクトリ -p 出力ディレクトリ

詳細は、http://www.naturaldocs.org/running.html

NaturalDocs.batはパスが通らない可哀想な子のためのバッチで、

 “perl NaturalDocs %NaturalDocsParams%”. 

の部分を

 “perl “C:\Program Files\Natural Docs\NaturalDocs" %NaturalDocsParams%”. 

とNatural Docsを解凍したフォルダをフルパスで指定して、
ソースのあるディレクトリに置いて

NaturalDocs -i プロジェクトディレクトリ -o FramedHTML 設定ファイルディレクトリ -p 出力ディレクトリ

とすると、ドキュメントが作成されます。

詳細は、http://www.naturaldocs.org/troubleshooting.html

●NaturalDocs書き方
NaturalDocsはほぼ以下の記載で書けちゃいます。

“keyword: title”
説明

クラスなら

Class: SandBox
描画テストを行うためのクラス。

変数なら

    variable: child
    描画、マウスハンドラ用スプライト

関数なら

　　Function: undo
　　描画を巻き戻す
		

と、同じような書き方です。
またvariableはvarでも代用可能で、いろいろと融通がききます。

詳しくは、
こんな感じのルールと、
http://www.naturaldocs.org/documenting/walkthrough.html

こんな感じのキーワードがあります。
http://www.naturaldocs.org/keywords.html

サンプルソースは以下のような感じです。

package{
    import flash.display.Sprite;	
    import flash.events.MouseEvent;
    import flash.utils.Timer;
    import flash.events.TimerEvent;
    import flash.events.Event;
    import flash.net.*;
    import Model.*;
    
    	
    /*
         Class: SandBox
	 描画テストを行うためのクラス。
	 	
    */
    public class SandBox extends Sprite{
    	
    	/*
    		variable: child
    		描画、マウスハンドラ用スプライト
    	*/
        private var child:Sprite;
        /*
    		variable: PointArray
    		クリック座標保持用配列
    	*/
       	private var PointArray:Array;
   		
   	/*
    		variable: timer
    		インターバルタイマ
    	*/
	private var timer:Timer;
		
	/* 
		variable: UndoData
		アンドゥ用データ保存配列          
	*/
	private var UndoData:Array;
		
		
		
		
		
	/*
	 	Constructor: SandBox
		コンストラクタ
		
	*/
	public function SandBox()
	{
	  PointArray = new Array();
	  UndoData = new Array();
		
	  child = new Sprite();
          child.focusRect = false;
          //背景クリア
          child.graphics.beginFill(0xffffff);
          child.graphics.drawRect(0,0,1024,768);
          child.graphics.endFill();
          addChild(child);
	 	  
 	  //イベント追加
          child.addEventListener(MouseEvent.MOUSE_DOWN,mouseDownHandler);
          
               
          timer=new Timer(40,0);
          timer.addEventListener(TimerEvent.TIMER,onTick);
          timer.start();
          
          
		 
	}
	 	
	 	
	/*
		Function: onTick
		タイマー処理
	 		
		Parameters:
	        evt - タイマーイベントのデータ
	*/
	private function onTick(evt:TimerEvent):void 
	{
	  //背景クリア	
	  child.graphics.beginFill(0xffffff);
          child.graphics.drawRect(0,0,1024,768);
          child.graphics.endFill();
          
          child.graphics.beginFill(0x000000);
          child.graphics.drawRect(500,100,100,100);
          child.graphics.endFill();
          
          child.graphics.beginFill(0x0000ff);
          child.graphics.drawRect(600,100,100,100);
          child.graphics.endFill();
          
         
          
          var i:int;
          for(i=0;i<PointArray.length;++i){
	          child.graphics.beginFill(0xff0000);
		      child.graphics.drawCircle(PointArray[i].getx(),PointArray[i].gety(),20);
	 		  child.graphics.endFill();
          }
          
	}
	 	
 	/*
 		Function: mouseDownHandler
 		マウスダウン処理
 		
 		Parameters:
		evt - マウスイベントのデータ
	    
  		Returns:
		戻り値なし

 	*/
 	private function mouseDownHandler(evt:MouseEvent):void {
	 		
            if(500 < mouseX && mouseX < 600){
            	if(100 < mouseY && mouseY < 200){
            		undo();
            		return;
            	}
            }
         
         
            if(600 < mouseX && mouseX < 700){
            	if(100 < mouseY && mouseY < 200){
            		redo();
            		return;
            	}
            }
         
         
	 		
	    PointArray.push(new MyPoint(mouseX,mouseY));
        }
        
        /*
           Function: undo
	   描画を巻き戻す
	 		
	   See Also:
      	   <redo>
	*/
        private function undo():void
        {
        	if(PointArray.length  > 0){
	        	UndoData.push(PointArray.pop());
	        }
        }
        
        /*
            Function: redo
	    描画の巻き戻しをキャンセル
	 		
	     See Also:
      	     <undo>
	 */
        private function redo():void
        {
        	if(UndoData.length  > 0){
	        	PointArray.push(UndoData.pop());
	        }
        }
      
    
    }
}

●まとめ
NaturalDocs面白いと思います。
僕はASDocを今までつかっていないのですが、
NaturalDocsは、コメントを極めて自然にかけて、出力されるドキュメントも機能的だと思いました。
まだ調べきれていない機能もあるので、もう少し使ってみたいと思います。

ASDocを今まで使っていた人の意見とかは聞いてみたいですねー、ASDocのこの機能がないと使い物にならないとか、
そういう意見が知りたいです。