Many objects are undocumented. about pio HOT 8 CLOSED

承知しました。取り急ぎ。

from pio.

@yasuhito

今、rake yard:list_undocで確認したものの
ドキュメンテーションを進めています。

初歩的なことで大変申し訳ありませんが、
ドキュメントの粒度について、

1:コメントのみコメント
2:戻り値・引数・パラメータなどコメント

と分けようかと考えています。

new, read, to_binary、各フィールドにアクセスする際のメソッドなどを重点的に詳細に追記しておき、
内部でのみ利用しているメソッドなどは、コメント(or何も記載しない)のみ追記するような感じですといかがでしょうか。

無作法でしたら申し訳ございませんが、
何卒ご教授のほどお願いしたく存じます。

from pio.

はい、その方針でよいと思います。
private なメソッドはコメントは原則なしで OK です。

from pio.

承知しました。
ありがとうございます。

from pio.

最低限のドキュメントについては rubocop でチェックしているので、とりあえず Travis が通っていれば OK としましょう。

from pio.

承知しました。対応遅くて済みません。

from pio.

f7fd7c7 で inch というドキュメンテーション支援の gem を入れておきました。

• inch と打てばドキュメンテーションが必要そうなメソッドを列挙してくれます。
• inch show メソッド名 とすれば、具体的に何が足りないか教えてくれます。

$ inch show "Pio::Dhcp::FieldUtil#relay_agent_ip_address"

# Pio::Dhcp::FieldUtil#relay_agent_ip_address
┃ -> /Users/yasuhito/play/pio/lib/pio/dhcp/field_util.rb:79
┃ ---------------------------------------------------------
┃ Grade: U - Undocumented
┃ ---------------------------------------------------------
┃ + Add a comment describing the method
┃ + Add a code example (optional)
┃ + Describe what 'relay_agent_ip_address' returns
┃ + Describe what 'relay_agent_ip_address' returns
┃ ---------------------------------------------------------

詳しくは inch のドキュメントを参照してみてください。

from pio.

ありがとうございます。
承知しました！

from pio.