3

私は自分のコードを文書化することに興味があります。その大部分は、新しいクラスを作成しないスクリプトです。

YARDドキュメントを読んで、実際にいくつかの YARD ドキュメントを実装しようとすると、定義されたクラス内で YARD タグを宣言しているようです。以下のサンプルコードのように、クラスを作成したり、クラスに新しいメソッドを追加したりするときに、YARD をうまく使用できまし@authorた@example。

#!/usr/bin/env ruby -wKU

## a YARD test

class String

  # Prints a string using two supplied strings
  #
  # @param str1 [String] A string to print
  # @param str2 [String] A string to print
  # @return [String] A printed string
  def yardTest(str1, str2)
    p sprintf("Hello, %s, %s", str1, str2)
  end   

end

ここに画像の説明を入力

私の質問は次のとおりです。

  1. クラスを定義せずに YARD タグを使用してコード (特にメソッド) を文書化する方法はありますか?
  2. そうでない場合、コードに広範なコメントを入れる以外に、どのような解決策がありますか?
4

1 に答える 1

2

クラスベースまたはモジュールベースのメソッドの場合と同様に、スクリプト内のメソッドを文書化するだけです。YARD は、それらを「トップ レベルの名前空間」の一部として文書化する必要があります。

スクリプトへの次の変更は、ラッパーを削除して機能します。class String

#!/usr/bin/env ruby -wKU

# Prints a string using two supplied strings
#
# @param str1 [String] A string to print
# @param str2 [String] A string to print
# @return [String] A printed string
def yardTest(str1, str2)
  p sprintf("Hello, %s, %s", str1, str2)
end

ユーザー向けにスクリプトの API を文書化することを検討することもできますが、これはもちろん別の目的と対象者向けです。

また、アクションを実行するメソッドからコマンドライン インターフェイスを分離することも検討してください。この場合、適切なモジュールとクラスを作成することになります。これは、リモートで複雑なものを作成する場合の自然なパターンであり、将来スクリプト間でロジックを共有したり、コマンド ラインから呼び出されないものにロジックを共有したりできるようになります。gemを見ることができます。thorこれは、コマンドライン スクリプトを作成するためのフレームワークであり、優れた抽象化パターンに従うコマンドライン インターフェイスの例が含まれています。Thor は、コマンドライン スクリプトに標準的な練習方法とヘルプを簡単に含めることをサポートしています。

于 2013-10-19T11:00:04.947 に答える