YARDを使用したRuby on Railsプロジェクトのドキュメントの作成

こんにちは、ハラジテリ！ Ruby on Railsプロジェクトのドキュメントを作成するプロセスを整理する方法についての記事がサイト上にないことがわかりました。 この問題を修正してください。



この記事では、 YARD gemを使用して鉄道プロジェクトの有能なドキュメントを作成し、このドキュメントがプレゼンテーション形式で提示されるドキュメントを自動的に生成する方法について説明します。 ドキュメントの例は、 ValiIzRashkiサイトコードにあります 。



まず、少しの理論。 これはキャプテンのように思えるかもしれませんが、私の目標は、コードのドキュメントを書いていない人に、これが非常に有用であり、まったく難しくないことを確信させることです。 ドキュメントの下では、原則として、サイトコードが記述されているコードまたは別のドキュメントに関するコメントを理解してください。

理論：なぜドキュメントを書くのですか？

答えは簡単です。コードをより理解しやすくするためです。 同僚があなたの注意をそらし、千の質問をする必要はありません。また、あなた自身のコードの複雑さを覚えて頭を悩ます必要はありません。 明確なコードでは、バグを見つけて破壊するのが簡単です。 また、顧客または設計者が突然思いついたコードに新しい機能を追加することも簡単になります。

しかし、最高のコメントは書く必要のないものですか？

実際、理解するために必要なコメントの量が最小限になるように、このような明確なコードを書く必要があります。 これは、フレンドリ名の変数、予測可能なモジュラーコード構造などを使用して実現されます。 私自身はコメントに頼らずにコードを書きました。 しかし、彼はすぐに、コードのコメントを読むのに2秒を費やす方が、最も理解しやすいコードでさえ5-10を読んで理解するよりも有益であることに気付きました。 いずれにせよ、コードの本質を通常の言語で伝える方がはるかに簡単で効率的です。

しかし、ドキュメントを書くのは非常に長い時間です！

種類はありません。 ここで説明した方法では、先ほど作成したコードのドキュメントを作成するのに、平均して1分かかります。 この分は、次回コードに戻るとすぐに報われます。



ドキュメントに加えてさらに引数が必要な場合は、このトピックに関する賢明な人々による他の記事を読むことができます。たとえば、 このプレゼンテーションを表示できます。 そして、私たちは練習に移ります。

練習：YARD構造化コメント

最初、Ruby on Railsプロジェクトで、特定の構造を持たないコメントを書きました。 各方法の前に、そこで何が起こっているかを簡単に書きました。 次に、たとえば、このメソッドがとるパラメーターを記述するのが便利だと思いました。 そしてそれが返すものも。 質問は、どこでも単一のコメントテンプレートに固執しないのですか？





gem YARDが見つかりました。 その本質は、リモートでxml / htmlに似た特定の単純な構文を使用してコードにコメントを書くことです。 その後、HTMLファイルを作成するコマンドを実行します。このコマンドでは、コードとドキュメントが便利な形式でペイントされます。 RDOC gemはアナログですが、その構文は私にはもっと複雑に思えました。



宝石をセット

$ gem install yard
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

gemfileに追加するか

  gem 'yard'
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

バンドルインストールを実行します。



valiizrashki.ruのメソッド例をご覧ください

 def try_to_evacuate(country_id) country = Country.find(country_id) if country.allows_immigrants? evacuate! true else false end end
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

この方法は、他の国への移住が可能かどうかを判断し、避難します。 そのため、メソッドの宣言の前にコメントの形式で記述します。

 # ,         def try_to_evacuate(country_id) country = Country.find(country_id) ...
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ノックボタンをクリックすると、メソッドが呼び出されます。 これをYARDタグ@note



、さまざまな追加データを処理します。 構文は次のようになります。

 @_ ()  
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

複数の行を1つのタグに収める場合は、タブを使用します

 @_      
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

メソッド宣言の前に、同じ場所にある@note



タグで呼び出し場所に関する情報を書き留めます。

 # ,         # @note      "" def try_to_evacuate(country_id) ...
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

パラメーターは、 @param



タグを使用してパラメーターを受け入れると記述します。 このパラメーターのデータ型は角かっこで記述され、その後にパラメーターの説明が続きます。

 # @param country_id [Integer] id 
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

@return



タグを使用して、このメソッドが返すものを正確に記述します。 ここで、角括弧内に返されるデータのタイプを書き込みます。値の説明です。

 # @return [Boolean]   
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

明確にするために、このメソッドの使用例を示します。 @example



タグを使用してこれを行います。この場合、タブを使用します。

 # @example # try_to_evacuate(2)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

また、すぐにジャンプできるように、 @see



タグを使用して国モデルのドキュメントへのリンクを残します。

 # @see Country
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

結果は次のとおりです。

 # ,         # @param country_id [Integer] id  # @note      "" # @example # try_to_evacuate(2) # @return [Boolean]    # @see Country def try_to_evacuate(country_id) country = Country.find(country_id) if country.allows_immigrants? evacuate! true else false end end
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

YARDのドキュメントには、 このリンクで学習できる他のタグがあります。

ドキュメンテーションの時間！

信じられないほど数学的にするには、 .yardopts



というプロジェクトに次の内容の構成ファイルを作成します。

 --private --protected -o doc/ruby
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

その後、ターミナルのプロジェクトフォルダーにあるターミナルに移動し、そこでコマンドを実行します

 $ yard
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

doc / ruby​​フォルダーが作成されました。 エクスプローラーで開き、_index.htmlを開きます。 ブラウザで、メソッドに切り替えてこれを確認します。



よさそうだ。 また、モデルメソッドへの参照が機能します。



なぜ設定ファイルを作成したのですか？ そのため、毎回単純なyard



コマンドでドキュメントの生成を開始できます。 ファイルの最初の2行はプライベートメソッドをドキュメントに追加する役割を果たし、3行目はドキュメントが表示されるフォルダーを設定します。

ボーナス：coffeescriptの文書化

coffeescriptについては、 codoと呼ばれる同様の構文と機能を備えたツールを作成しました 。 ハックコードのドキュメントに自分自身を制限し、スクリプト用に作成しない理由はありません。



数値をラジアンに変換する文書化された関数の例：

  #    # @param x [Integer]  # @return [Integer]  rad:(x) -> x * Math.PI / 180
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

プロジェクトルートに.codoopts



ファイルを作成し、そこに書き込みます。

 -o doc/coffee
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

その後、プロジェクトのルートでコマンドを実行すると

 $ codo
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

doc / coffeeフォルダーにcoffeescriptのドキュメントを作成します。



完了、あなたは素晴らしいです！

おわりに

最後に、ドキュメントの自動生成を使用しない場合でも、構造化された方法でコードにコメントを書き始めることをお勧めします。 それはあなたとあなたの同僚の生活を楽にします！