joppot

コピペで絶対動く。説明を妥協しない

プログラミング

gemspecのsummary項目とdescription項目の違いに付いて

投稿日:


89h

概要

みなさんこんにちはcandleです。

gemを自作していたら、gemspecのところでsummaryとdescriptionの違いが分からなかったので、
調べたら、公式ページに書いてあったので、まとめておきます。


参考にしたサイト

http://guides.rubygems.org/specification-reference/#description
http://guides.rubygems.org/specification-reference/#summary


summaryとdescriptionの違いについて

一般に、gemを作成すると「Gem名.gemspec」というファイルが作成され、その中の項目にsummaryとdescriptionがあります。

公式にサイトにはsummaryは

“A short summary of this gem’s description. Displayed in `gem list -d`.
The description should be more detailed than the summary.”

とあります。訳すと以下の様になります。

“summaryの項目はdescriptionより簡潔に記述します。
summaryは`gem list -d`コマンドを使用した時に表示されます。”

サンプルを見ると、だいたい1行で書く事が推奨されているっぽいです。

s.summary = "This is a gem that will help your coding"

一方、descriptionは以下の様に記述されています。

“A long description of this gem
The description should be more detailed than the summary but not excessively long. A few paragraphs is a recommended length with no examples or formatting.”

訳すと。

“gemに付いての比較的長い説明。
descriptionはsummaryよりも長く、詳しく書くが、長過ぎない様に気をつける。
推奨している長さは2〜3段落くらいの文章構成である。”

例では以下の様に書かれています。

s.description = <<-EOF
  Rake is a Make-like program implemented in Ruby. Tasks and
  dependencies are specified in standard Ruby syntax.
EOF

長過ぎないように書くのが親切かと。

まとめ

ユーザーに親切なgemの記述を目指すのは大変ですが、出来るところからやっていきましょう。

スポンサードリンク

「為になったなぁ」と思ったら、シェアお願いします。

-プログラミング
-,

執筆者:


comment

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

関連記事

railsのcarrierwaveとremotipartで画像のアップロードを非同期にしjsonを受け取る

概要 みなさんこんにちはcandleです。今回はremotipartとcarrierwaveを使って画像のアップロードをajax化したいと思います。 railsのフォームはremote設定をするだけで …

phpのsnappyライブラリをmacで使用して、webサイトのサムネイルを取得する

概要 みなさんこんにちはcandleです。今回はsnappyを使用して、ウェブサイトのサムネイルを自動的に取得したいとおもいます。 snappyはそれ自体がhtmlを画像にするスクリプトではなく、wk …

fabricのsshのネットワーク設定でパスワードか公開鍵を使って認証する

概要 皆さん今日はcandleです。今回はsshを使ったfabricの設定をしましょう。 一般にsshにはパスワード認証と公開鍵認証があるので、そのどちらも試してみましょう。 もちろんセキュリティ面で …

railsのroutesでhttpのGETやPOSTを指定してルーティングを表示する

概要 みんさんこんにちはcandleです。今回は少し頭をひねれば分かる事ですが、少し迷ったので、記事にまとめました。 railsですごいwebアプリケーションを作っていると、ルーティングが複雑きわまり …

railsのrakeで作成したカラムの型とdefault値を変更する方法

概要 みなさんこんにちはcandleです。今回はrakeコマンドのややこしいところを扱います。 rakeコマンドはわりと便利で、データベースのカラムの追加や型の変更をマイグレーションファイルから読み込 …

  • English
  • 日本語

ベンチャー企業のCTOをやってます。大学時代にプログラミングを始め、javaから入門し、C++へて、PHPへと進み、会社ではRailsを使用。自動化が大好きなプログラマー