New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

コピペ可能なサンプルコードを整備する #433

Open
tbpgr opened this Issue Jul 18, 2017 · 129 comments

Comments

Projects
None yet
@tbpgr
Contributor

tbpgr commented Jul 18, 2017

貢献希望者

貢献希望者はruremaの活動に関する情報共有をするesaにおいでください 🐾
下記の招待URLから参加できます。

https://rurema.esa.io/

https://rurema.esa.io/team/invitations/member-003dab4dfc293b59bcdf01a2627024e6

サンプルコード追加手順

組み込みクラスサンプル追加対象リスト

自分が担当するクラスのヨコに名前を書いてください。
優先度の高いものから作りたい場合は、以下のアクセス解析結果で上位のものから
はじめるとよいです。

背景

結城先生から、Twitterで以下のような指摘がありました。

Rubyのドキュメントは、
「そのままコピペして動く典型的なコードを最初に見せてほしい」
という点だけが要望。requireが抜けてたり、そもそも典型的コード例がなかったり、

なお、以下の関連ツイートの流れ上「るりま」に対する指摘であることを確認済みです。
(ruby-doc ではない、という意味)

RubyでSecureRandomを使いたいと思い、Googleで"SecureRandom Ruby"を検索しました。
一番上に来るのは Ruby 2.4.0 の module SecureRandom のページでした
そこに書かれた例を試してみると動きません。require 'securerandom' を追加したら動きました 。
例には書かれてないけど「SecureRandomを使うには require 'securerandom'を書く」は当然の知識>なのかしら。

※なお、上記のIssueは修正済(ありがとうございます)

関連ツイート

前提

結城先生がいうところの

「そのままコピペして動く典型的なコード」

というのは SSCCE に近いものではないか、と考えています。

Short (Small) - Minimise bandwidth for the example, do not bore the audience.
Self Contained - Ensure everything is included, ready to go.
Correct - Copy, paste, (compile,) see is the aim.
Example - Displays the problem we are trying to solve.

http://sscce.org/ より

以降、 SSCCE として表記します。

なぜ SSCCE が大切か?

SSCCE は StackOverflow などでプログラムの例を示す際の好ましい形式を明文化したものですが、
その利点はプログラムのリファレンスに付属するサンプルに関しても適用されそうです。

  • 誰でも同じコードをコピペするだけで動かして確認できる
  • 最小の手間で対象を理解できる

仮にこれらの恩恵が無かった場合は

  • コピペして動かない部分に関して各自が予測して理解する必要がある
  • 理解に手間がかかる

ということになります。

現状

現状、るりまのドキュメントにおいて各メソッドに対するサンプルコードは
以下のような状態のいずれかになっています。

  • サンプルがあり、SSCCEになっている
  • サンプルがあり、SSCCEになっていない
  • サンプルがない

サンプルがあり、SSCCEになっていない

header
  # Content-Type: text/html

header("text/plain")
  # Content-Type: text/plain

header({"nph"        => true,
        "status"     => "OK",  # == "200 OK"
          # "status"     => "200 GOOD",
        "server"     => ENV['SERVER_SOFTWARE'],
        "connection" => "close",
        "type"       => "text/html",
        "charset"    => "iso-2022-jp",
          # Content-Type: text/html; charset=iso-2022-jp
        "language"   => "ja",
        "expires"    => Time.now + 30,
        "cookie"     => [cookie1, cookie2],
        "my_header1" => "my_value"
        "my_header2" => "my_value"})
  • "my_header1" => "my_value" の行末に半角カンマがない
  • require "cgi" がない
  • header を実際に使う場合は cgi のインスタンスが必要だが省略してある
  • cookie1, cookie2 が未宣言

サンプルがない

require "cgi"
CGI.accept_charset # => UTF-8
CGI.accept_charset=("ascii-8bit")
CGI.accept_charset # => ascii-8bit

議題

  • サンプルが SSCCE になっていないものを SSCCE にする?
  • サンプルがないものに SSCCE なサンプルを追加する?
  • 対象はすべてなのか、何か基準をもうけたうえで一部に適用するのか?

その他 懸念点

  • どの Version を対象とするか?

意思表明

実際に着手するとしたら以下のような手順になると思っています。

  1. 対応が必要かどうか判断するためドキュメント化されている全メソッドのリストを作る
  2. 1のリストに対してサンプル記載状況をまとめていく
    • SSCCEになっている
    • SSCCEになっていない
    • サンプルがない
  3. メソッドに付属するサンプルコードを記載ガイドライン(SSCCE的なもの)を wiki にまとめる
    • 今後の運用の基準にする
  4. リストアップ結果の量に応じて協力者を集う
  5. 協力者と手分けしてSSCCEを仕上げていく
    • 個別に Pull Request をしていく

2の作業は自動化できると嬉しいですが、おそらく手動(人の目で判断)になると思っています。
5の作業についても同様です。

実際に対応するという意思決定をした場合、
上記の全体に関して手を動かす気持ちがあります。

@tbpgr

This comment has been minimized.

Show comment
Hide comment
@tbpgr

tbpgr Jul 18, 2017

Contributor

想定のずれなどありましたらご指摘よろしくお願いいたします。

Contributor

tbpgr commented Jul 18, 2017

想定のずれなどありましたらご指摘よろしくお願いいたします。

@okkez

This comment has been minimized.

Show comment
Hide comment
@okkez

okkez Jul 19, 2017

Member

結城さんの話題はちらっと見て、スルーしてたのでこうして動いてくれる人が出てきてくれてうれしいです。

人力でリスト化するのはとても大変で辛いだけだし、手を動かす人も少ないのであんまりやりたくないです。少人数で人力でやるとリスト化だけで燃え尽きてしまいます。。。
💭 現状で月に数件PRが来る程度
全部で約15000から18000エントリ(メソッドシグニチャの違いを含めるともっと)あるので、手動でやるのはナンセンスだと思います。
協力者は常に募集中なので、どんどん来てもらえると 🙏

体系的・機械的にやるとしたら以下の感じがいいかなぁと思います。

  1. コード部分を抽出して自動実行し、結果を見やすく表示する機能を追加する。必要であれば、記法の拡張も行う。
    • 現状は、ほぼインデントで整形済みテキストをコードブロックとして扱っています。整形済みテキストは他の目的でも使用しているので、整形済みテキストを単純に「コード」として扱うと問題があります
    • 構想だけはあって実装してない機能だった。。。
  2. ↑で追加した機能を動かしてRubyのコードしてエラーのあるものを修正する
    • エラーの出ないサンプルコードは既にSSCCEになっているものと機械的に判断できる
    • 今、サンプルコードが無いものは重要でない・使用頻度が低い可能性が高いと考えられるのであとまわしにする
  3. サンプルコードの無いものをゆるゆるとやっていく
    • 1で追加して機能を使ってサンプルコードのないエントリもわかるような機能を追加する

メソッドに付属するサンプルコードを記載ガイドライン(SSCCE的なもの)を wiki にまとめる

これは、今すぐに着手できると思います。Wiki にページを用意して書いていってもらえれば 🙏
http://sscce.org/ のリンクだけでもいい気がしますが、さらっとサマリを書いて良い例・悪い例とこのプロジェクト特有の事情(記法の説明など)があれば書くのがいいと思います。

Member

okkez commented Jul 19, 2017

結城さんの話題はちらっと見て、スルーしてたのでこうして動いてくれる人が出てきてくれてうれしいです。

人力でリスト化するのはとても大変で辛いだけだし、手を動かす人も少ないのであんまりやりたくないです。少人数で人力でやるとリスト化だけで燃え尽きてしまいます。。。
💭 現状で月に数件PRが来る程度
全部で約15000から18000エントリ(メソッドシグニチャの違いを含めるともっと)あるので、手動でやるのはナンセンスだと思います。
協力者は常に募集中なので、どんどん来てもらえると 🙏

体系的・機械的にやるとしたら以下の感じがいいかなぁと思います。

  1. コード部分を抽出して自動実行し、結果を見やすく表示する機能を追加する。必要であれば、記法の拡張も行う。
    • 現状は、ほぼインデントで整形済みテキストをコードブロックとして扱っています。整形済みテキストは他の目的でも使用しているので、整形済みテキストを単純に「コード」として扱うと問題があります
    • 構想だけはあって実装してない機能だった。。。
  2. ↑で追加した機能を動かしてRubyのコードしてエラーのあるものを修正する
    • エラーの出ないサンプルコードは既にSSCCEになっているものと機械的に判断できる
    • 今、サンプルコードが無いものは重要でない・使用頻度が低い可能性が高いと考えられるのであとまわしにする
  3. サンプルコードの無いものをゆるゆるとやっていく
    • 1で追加して機能を使ってサンプルコードのないエントリもわかるような機能を追加する

メソッドに付属するサンプルコードを記載ガイドライン(SSCCE的なもの)を wiki にまとめる

これは、今すぐに着手できると思います。Wiki にページを用意して書いていってもらえれば 🙏
http://sscce.org/ のリンクだけでもいい気がしますが、さらっとサマリを書いて良い例・悪い例とこのプロジェクト特有の事情(記法の説明など)があれば書くのがいいと思います。

@tbpgr tbpgr changed the title from コピペ可能なサンプルコードを整備する? to コピペ可能なサンプルコードを整備する Jul 19, 2017

@tbpgr

This comment has been minimized.

Show comment
Hide comment
@tbpgr

tbpgr Jul 19, 2017

Contributor

@okkez お忙しい中、さっそくの確認ありがとうございます。

運用背景に関して

人力でリスト化するのはとても大変で辛いだけだし、手を動かす人も少ないのであんまりやりたくないです。少人数で人力でやるとリスト化だけで燃え尽きてしまいます。。。
💭 現状で月に数件PRが来る程度
全部で約15000から18000エントリ(メソッドシグニチャの違いを含めるともっと)あるので、手動でやるのはナンセンスだと思います。

把握です。運用背景の明示ありがとうございます😄

協力者募集に関して

協力者は常に募集中なので、どんどん来てもらえると 🙏

タイミングをみてよしなに呼びかけてみます。

純粋にるりまの宣伝もしようと思います。
立場上私の情報を見ている人にRubyの初心者が一定数いると考えるためです。

対象の抽出とサンプル拡充方法について

体系的・機械的にやるとしたら以下の感じがいいかなぁと思います。

  1. コード部分を抽出して自動実行し、結果を見やすく表示する機能を追加する。必要であれば、記法の拡張も行う。

なるほど!

まだしっかり全体をみていなかったのですが、
ざっとみて特殊なフォーマットにみえたので印象として機械的な抽出が難しそうかな、
と思い込んでいました。
一定のルールで抽出できるならそれが1番ですね。
提示いただいた手順に異論ありません。 👍

るりまの現状のファイル構成やファイルフォーマットについて詳細には把握できていないので
まずはWikiや実ファイルをみて予習しておこうと思います。

SSCCE について

メソッドに付属するサンプルコードを記載ガイドライン(SSCCE的なもの)を wiki にまとめる

これは、今すぐに着手できると思います。Wiki にページを用意して書いていってもらえれば 🙏

👌 です。
このプロジェクト特有の事情(現Wikiを確認します)を確認の上、該当ページを追加しておきます。
(追加したらここでコメントします)

Contributor

tbpgr commented Jul 19, 2017

@okkez お忙しい中、さっそくの確認ありがとうございます。

運用背景に関して

人力でリスト化するのはとても大変で辛いだけだし、手を動かす人も少ないのであんまりやりたくないです。少人数で人力でやるとリスト化だけで燃え尽きてしまいます。。。
💭 現状で月に数件PRが来る程度
全部で約15000から18000エントリ(メソッドシグニチャの違いを含めるともっと)あるので、手動でやるのはナンセンスだと思います。

把握です。運用背景の明示ありがとうございます😄

協力者募集に関して

協力者は常に募集中なので、どんどん来てもらえると 🙏

タイミングをみてよしなに呼びかけてみます。

純粋にるりまの宣伝もしようと思います。
立場上私の情報を見ている人にRubyの初心者が一定数いると考えるためです。

対象の抽出とサンプル拡充方法について

体系的・機械的にやるとしたら以下の感じがいいかなぁと思います。

  1. コード部分を抽出して自動実行し、結果を見やすく表示する機能を追加する。必要であれば、記法の拡張も行う。

なるほど!

まだしっかり全体をみていなかったのですが、
ざっとみて特殊なフォーマットにみえたので印象として機械的な抽出が難しそうかな、
と思い込んでいました。
一定のルールで抽出できるならそれが1番ですね。
提示いただいた手順に異論ありません。 👍

るりまの現状のファイル構成やファイルフォーマットについて詳細には把握できていないので
まずはWikiや実ファイルをみて予習しておこうと思います。

SSCCE について

メソッドに付属するサンプルコードを記載ガイドライン(SSCCE的なもの)を wiki にまとめる

これは、今すぐに着手できると思います。Wiki にページを用意して書いていってもらえれば 🙏

👌 です。
このプロジェクト特有の事情(現Wikiを確認します)を確認の上、該当ページを追加しておきます。
(追加したらここでコメントします)

@okkez

This comment has been minimized.

Show comment
Hide comment
@okkez

okkez Jul 20, 2017

Member

よろしくお願いします!

Member

okkez commented Jul 20, 2017

よろしくお願いします!

@tbpgr

This comment has been minimized.

Show comment
Hide comment
@tbpgr

tbpgr Jul 24, 2017

Contributor

@okkez Wiki にページを追加しました。
問題点などありましたらお知らせください。

ReferenceManualFormatDigest のメソッドの説明の末尾にサンプルコードガイドラインへのリンクを追加しました。

_072517_122044_am

Contributor

tbpgr commented Jul 24, 2017

@okkez Wiki にページを追加しました。
問題点などありましたらお知らせください。

ReferenceManualFormatDigest のメソッドの説明の末尾にサンプルコードガイドラインへのリンクを追加しました。

_072517_122044_am

@hanachin

This comment has been minimized.

Show comment
Hide comment
@hanachin

hanachin Jul 31, 2017

Contributor

インデントされたテキストや//emlistでマークアップされたコード(かもしれない)部分はこんな感じで取れそうです。

require 'bitclust'
require 'yaml'
umap = BitClust::URLMapper.new({})
compiler = BitClust::RDCompiler.new(umap, 1, {force: true})

list = []
compiler.define_singleton_method(:list) do
  lines = unindent_block(canonicalize(@f.break(/\A\S/)))
  while lines.last.empty?
    lines.pop
  end
  out = StringIO.new
  lines.each do |line|
    out.puts line
  end
  list << out.string
end

emlist = []
compiler.define_singleton_method(:emlist) do
  @f.gets   # discard "//emlist{"
  out = StringIO.new
  @f.until_terminator(%r<\A//\}>) do |line|
    out.puts line.rstrip
  end
  emlist << out.string
end

compiler.define_singleton_method(:method_signature) do |_sig_line, _first|
  # stub
end

Dir["refm/**/*"].each do |rd|
  next if File.directory?(rd)
  src = File.read(rd)
  begin
    compiler.compile(src)

    (list + emlist).each do |maybe_code|
      # ...
    end
  rescue
    $stderr.puts "#{rd}: #{$!.message}"
  ensure
    list = []
    emlist = []
  end
end

# ...と書いた部分でRubyVM::InstructionSequence.compileが通るか試してみたり雑にdockerの中で実行してみたり_builtinディレクトリ以外のファイルでrequireがないコードをリストアップしてみたりするとコピペ可能になっていないコード探せないかな〜 ?と考えています。

ぱっとみた感じ他の目的でも使用している整形テキスト、行番号付きのコード、irbをはったもの、コンソールのプロンプト、rubyの実行コマンドが混ざっていたり、標準出力、エラーの内容、メソッドの戻り値など実行結果の書き方のバリエーションがいくつかありそうだなーという感じの印象です。

追記

gistにあげてちょこちょこ更新してます

https://gist.github.com/hanachin/deafd221e0f667ffb60f5d68241669f9

更に追記

こっちのリポジトリで管理するようにしました
https://github.com/hanachin/rurema-scripts

Contributor

hanachin commented Jul 31, 2017

インデントされたテキストや//emlistでマークアップされたコード(かもしれない)部分はこんな感じで取れそうです。

require 'bitclust'
require 'yaml'
umap = BitClust::URLMapper.new({})
compiler = BitClust::RDCompiler.new(umap, 1, {force: true})

list = []
compiler.define_singleton_method(:list) do
  lines = unindent_block(canonicalize(@f.break(/\A\S/)))
  while lines.last.empty?
    lines.pop
  end
  out = StringIO.new
  lines.each do |line|
    out.puts line
  end
  list << out.string
end

emlist = []
compiler.define_singleton_method(:emlist) do
  @f.gets   # discard "//emlist{"
  out = StringIO.new
  @f.until_terminator(%r<\A//\}>) do |line|
    out.puts line.rstrip
  end
  emlist << out.string
end

compiler.define_singleton_method(:method_signature) do |_sig_line, _first|
  # stub
end

Dir["refm/**/*"].each do |rd|
  next if File.directory?(rd)
  src = File.read(rd)
  begin
    compiler.compile(src)

    (list + emlist).each do |maybe_code|
      # ...
    end
  rescue
    $stderr.puts "#{rd}: #{$!.message}"
  ensure
    list = []
    emlist = []
  end
end

# ...と書いた部分でRubyVM::InstructionSequence.compileが通るか試してみたり雑にdockerの中で実行してみたり_builtinディレクトリ以外のファイルでrequireがないコードをリストアップしてみたりするとコピペ可能になっていないコード探せないかな〜 ?と考えています。

ぱっとみた感じ他の目的でも使用している整形テキスト、行番号付きのコード、irbをはったもの、コンソールのプロンプト、rubyの実行コマンドが混ざっていたり、標準出力、エラーの内容、メソッドの戻り値など実行結果の書き方のバリエーションがいくつかありそうだなーという感じの印象です。

追記

gistにあげてちょこちょこ更新してます

https://gist.github.com/hanachin/deafd221e0f667ffb60f5d68241669f9

更に追記

こっちのリポジトリで管理するようにしました
https://github.com/hanachin/rurema-scripts

@znz

This comment has been minimized.

Show comment
Hide comment
@znz

znz Aug 1, 2017

Member

https://docs.ruby-lang.org/ja/latest/method/Enumerable/i/cycle.html のような意図的に無限ループになっている例もあるようなので、単純に自動で xmpfilter みたいなことをするのは難しそうなので、既存のものは syntax check ぐらいにして、実行結果を自動で入れたい場合は別のマークアップがあると良いのかもしれません。

Member

znz commented Aug 1, 2017

https://docs.ruby-lang.org/ja/latest/method/Enumerable/i/cycle.html のような意図的に無限ループになっている例もあるようなので、単純に自動で xmpfilter みたいなことをするのは難しそうなので、既存のものは syntax check ぐらいにして、実行結果を自動で入れたい場合は別のマークアップがあると良いのかもしれません。

@sho-h

This comment has been minimized.

Show comment
Hide comment
@sho-h

sho-h Aug 3, 2017

Member

syntax check

別Issue行きがいいかもですが、上記で得られたものをtravisに渡してsyntax checkさせると嬉しそうですね。...の部分でruby -cする新しいタスクを https://github.com/rurema/doctree/blob/master/Rakefile のデフォルトタスクに足したらいいとかですかねぇ。

Member

sho-h commented Aug 3, 2017

syntax check

別Issue行きがいいかもですが、上記で得られたものをtravisに渡してsyntax checkさせると嬉しそうですね。...の部分でruby -cする新しいタスクを https://github.com/rurema/doctree/blob/master/Rakefile のデフォルトタスクに足したらいいとかですかねぇ。

@hanachin

This comment has been minimized.

Show comment
Hide comment
@hanachin

hanachin Aug 19, 2017

Contributor

サンプルコードの無いものをゆるゆるとやっていく
1で追加して機能を使ってサンプルコードのないエントリもわかるような機能を追加する

サンプルコードがないもの雑に探すならこういう感じですね

% bitclust statichtml -o /tmp
% cd /tmp
% ruby -e 'methods = Dir["method/**/*.html"]; methods_with_example = methods.select{|m| File.read(m).include?("<pre>") }; puts "#{methods_with_example.count}/#{methods.count}"'
2628/11039
% ruby -e 'methods = Dir["method/**/*.html"]; methods_with_example = methods.select{|m| File.read(m).include?("<pre>") }; puts (methods - methods_with_example)'
method/-open-s-s-l=3a=3a-p-key=3a=3a-r-s-a/s/new.html
method/-open-s-s-l=3a=3a-p-key=3a=3a-r-s-a/s/generate.html
method/-open-s-s-l=3a=3a-p-key=3a=3a-r-s-a/c/-p-k-c-s1_-p-a-d-d-i-n-g.html
method/-open-s-s-l=3a=3a-p-key=3a=3a-r-s-a/c/-p-k-c-s1_-o-a-e-p_-p-a-d-d-i-n-g.html
...
method/-r-e-x-m-l=3a=3a-node/i/next_sibling_node.html
method/-r-e-x-m-l=3a=3a-node/i/parent=3f.html
method/-r-e-x-m-l=3a=3a-node/i/index_in_parent.html
method/-r-e-x-m-l=3a=3a-node/i/to_s.html
Contributor

hanachin commented Aug 19, 2017

サンプルコードの無いものをゆるゆるとやっていく
1で追加して機能を使ってサンプルコードのないエントリもわかるような機能を追加する

サンプルコードがないもの雑に探すならこういう感じですね

% bitclust statichtml -o /tmp
% cd /tmp
% ruby -e 'methods = Dir["method/**/*.html"]; methods_with_example = methods.select{|m| File.read(m).include?("<pre>") }; puts "#{methods_with_example.count}/#{methods.count}"'
2628/11039
% ruby -e 'methods = Dir["method/**/*.html"]; methods_with_example = methods.select{|m| File.read(m).include?("<pre>") }; puts (methods - methods_with_example)'
method/-open-s-s-l=3a=3a-p-key=3a=3a-r-s-a/s/new.html
method/-open-s-s-l=3a=3a-p-key=3a=3a-r-s-a/s/generate.html
method/-open-s-s-l=3a=3a-p-key=3a=3a-r-s-a/c/-p-k-c-s1_-p-a-d-d-i-n-g.html
method/-open-s-s-l=3a=3a-p-key=3a=3a-r-s-a/c/-p-k-c-s1_-o-a-e-p_-p-a-d-d-i-n-g.html
...
method/-r-e-x-m-l=3a=3a-node/i/next_sibling_node.html
method/-r-e-x-m-l=3a=3a-node/i/parent=3f.html
method/-r-e-x-m-l=3a=3a-node/i/index_in_parent.html
method/-r-e-x-m-l=3a=3a-node/i/to_s.html
@tbpgr

This comment has been minimized.

Show comment
Hide comment
@tbpgr

tbpgr Aug 22, 2017

Contributor

@hanachin もろもろありがとうございます。すばらしい! 👏

サンプルコードなしへの対応

サンプルコードなしは

11039 - 2628 = 8411件

ですか。
多いですね。

何らかの重要度に応じて一定の需要があるものを優先して作るとかがいいですかね?
例えば、もし現状るりまでGAを使っているならサンプルコード未作成のページのうち、
アクセス数トップN件を対象にする、とか。

サンプルの優先度さえ決まれば少なくとも人を集いつつ自分自身は粛々とサンプルを増やすことはできます。

Contributor

tbpgr commented Aug 22, 2017

@hanachin もろもろありがとうございます。すばらしい! 👏

サンプルコードなしへの対応

サンプルコードなしは

11039 - 2628 = 8411件

ですか。
多いですね。

何らかの重要度に応じて一定の需要があるものを優先して作るとかがいいですかね?
例えば、もし現状るりまでGAを使っているならサンプルコード未作成のページのうち、
アクセス数トップN件を対象にする、とか。

サンプルの優先度さえ決まれば少なくとも人を集いつつ自分自身は粛々とサンプルを増やすことはできます。

@tbpgr

This comment has been minimized.

Show comment
Hide comment
@tbpgr

tbpgr Aug 23, 2017

Contributor

1例として String#ascii_only? を追加してみました。

#518

特に問題なさそうなら持続可能なペースで粛々とサンプルを追加していきます。
(今後は逐一報告とかせずに黙々とやります)

Contributor

tbpgr commented Aug 23, 2017

1例として String#ascii_only? を追加してみました。

#518

特に問題なさそうなら持続可能なペースで粛々とサンプルを追加していきます。
(今後は逐一報告とかせずに黙々とやります)

@sho-h

This comment has been minimized.

Show comment
Hide comment
@sho-h

sho-h Aug 24, 2017

Member

Google Analysticsはたぶんつかってないと思いますので、何か参考にするとしたらdocs.ruby-lang.orgのアクセスログからアクセス件数順トップN件とかですかねぇ。

追加の流れは個人的には以下がいいですが、どうしましょ? > @okkez さん

  1. rdocにサンプルがあれば掲載
  2. 日本人向けにより良いサンプルがあれば追加で掲載(任意)

rdocのサンプルでないとしてもその理由がIssueかコミットログに残ってるとよりありがたいですけど、負担かもしれませんのでマージする方のお仕事にしてもいいかもしれません。(2だけ作業してもらって、1をマージした人が追加でコミットするなど

Member

sho-h commented Aug 24, 2017

Google Analysticsはたぶんつかってないと思いますので、何か参考にするとしたらdocs.ruby-lang.orgのアクセスログからアクセス件数順トップN件とかですかねぇ。

追加の流れは個人的には以下がいいですが、どうしましょ? > @okkez さん

  1. rdocにサンプルがあれば掲載
  2. 日本人向けにより良いサンプルがあれば追加で掲載(任意)

rdocのサンプルでないとしてもその理由がIssueかコミットログに残ってるとよりありがたいですけど、負担かもしれませんのでマージする方のお仕事にしてもいいかもしれません。(2だけ作業してもらって、1をマージした人が追加でコミットするなど

@okkez

This comment has been minimized.

Show comment
Hide comment
@okkez

okkez Aug 24, 2017

Member

アクセス解析はやってないですね。。。
アクセスログは見られますけど、確認したらサーバーを移設した影響で直近の約10日分しかログが残っていないです。
↓のとおり組み込みからやってるうちにデータが溜まると思うので、組み込み以外はアクセスログのデータを参考にするといいかもしれません。

組み込みは全部やらなきゃダメなので、組み込みからやればいいです。
作業の流れは、rdoc から持ってくるのでいいと思います。
rdoc にサンプルが無ければ、rdoc の方にもフィードバックするといいと思います。

Member

okkez commented Aug 24, 2017

アクセス解析はやってないですね。。。
アクセスログは見られますけど、確認したらサーバーを移設した影響で直近の約10日分しかログが残っていないです。
↓のとおり組み込みからやってるうちにデータが溜まると思うので、組み込み以外はアクセスログのデータを参考にするといいかもしれません。

組み込みは全部やらなきゃダメなので、組み込みからやればいいです。
作業の流れは、rdoc から持ってくるのでいいと思います。
rdoc にサンプルが無ければ、rdoc の方にもフィードバックするといいと思います。

@znz

This comment has been minimized.

Show comment
Hide comment
@znz

znz Aug 24, 2017

Member

「例:」をつけるかどうかとか、インデントの深さとかはサンプルコードによって違うようなので、ガイドラインで決まっていると悩まなくて良さそうです。

Member

znz commented Aug 24, 2017

「例:」をつけるかどうかとか、インデントの深さとかはサンプルコードによって違うようなので、ガイドラインで決まっていると悩まなくて良さそうです。

@tbpgr tbpgr referenced this issue Aug 24, 2017

Merged

Add String#b #520

@tbpgr

This comment has been minimized.

Show comment
Hide comment
@tbpgr

tbpgr Aug 24, 2017

Contributor

rdoc に関して

rdoc 側に example 追加有無の判断基準とかありますか?
例えば、ただの getter/setter 的なものへのサンプルはいらないよね、
というようにあえて example を書いていないものがあるかもしれない?
(rurema側で聞く話じゃないかもですが)

これによって、 rurema にも rdoc にもサンプルがなかった場合に、
rdoc 側にもフィードバックする基準を確認したいです。

ガイドラインの修正

「例:」をつけるかどうかとか、インデントの深さとかはサンプルコードによって違うようなので、
ガイドラインで決まっていると悩まなくて良さそうです。

例とインデントのルールが決まれば Wiki を変更しておきます。

個人的な意見としては

  • 「例」は無しがいいと思います
    • 理由は「例」があると1メソッドに複数サンプルがあったときの場合分けなどルールがめんどうになりそうだから
    • 例の記載がなくても表示フォーマットから例であることは自明であると感じられるから
  • インデントはどちらでも
    • 半角2
    • 半角4

追加でもう一つ

  • 出力値を併記するときに、サンプルコード内に p を書くか書かないかも統一しますか?
# p がないケース
"hello世界".chars # => ["h", "e", "l", "l", "o", "世", "界"]

# p があるケース
p "foo\n".chomp             # => "foo"

rdoc から全自動 or 半自動反映は可能だろうか?

これは可能性の話です。

以下の前提を満たすのならある程度の自動化ができそうな気がします。
具体的に中身を見ずに予想段階での話です。
rurema と Ruby の rdoc 双方に詳しい方がいたらピンとくるかも、ということで書いています。

  • 特定のメソッドのサンプルコードが Ruby の rdoc にあるけど rurema にないということをファイル名やファイル内の構造から特定可能
  • rurema でメソッドのサンプルコードを挿入する位置を特定可能

この2つを満たすなら、 rdoc から rurema にサンプルコードを自動移植してプルリクエストを投げる、
ぐらいのところまで自動化が可能かもしれない、と思いますがいかがでしょうか?

ただ、実際に rdoc のコードが rurema のガイドラインに沿ったものかどうかはわからないと思うので、
自動でプルリクを投げたあとに人間が確認する、というようになるのではと想像しています。

実現可能性は

  • いけそう?
  • むりそう?
  • 調べないとわからない

どれでしょうか?

この件の答えがでるまでは、 rdoc にサンプルがなくて rurema にもないものを追加していきます。

Contributor

tbpgr commented Aug 24, 2017

rdoc に関して

rdoc 側に example 追加有無の判断基準とかありますか?
例えば、ただの getter/setter 的なものへのサンプルはいらないよね、
というようにあえて example を書いていないものがあるかもしれない?
(rurema側で聞く話じゃないかもですが)

これによって、 rurema にも rdoc にもサンプルがなかった場合に、
rdoc 側にもフィードバックする基準を確認したいです。

ガイドラインの修正

「例:」をつけるかどうかとか、インデントの深さとかはサンプルコードによって違うようなので、
ガイドラインで決まっていると悩まなくて良さそうです。

例とインデントのルールが決まれば Wiki を変更しておきます。

個人的な意見としては

  • 「例」は無しがいいと思います
    • 理由は「例」があると1メソッドに複数サンプルがあったときの場合分けなどルールがめんどうになりそうだから
    • 例の記載がなくても表示フォーマットから例であることは自明であると感じられるから
  • インデントはどちらでも
    • 半角2
    • 半角4

追加でもう一つ

  • 出力値を併記するときに、サンプルコード内に p を書くか書かないかも統一しますか?
# p がないケース
"hello世界".chars # => ["h", "e", "l", "l", "o", "世", "界"]

# p があるケース
p "foo\n".chomp             # => "foo"

rdoc から全自動 or 半自動反映は可能だろうか?

これは可能性の話です。

以下の前提を満たすのならある程度の自動化ができそうな気がします。
具体的に中身を見ずに予想段階での話です。
rurema と Ruby の rdoc 双方に詳しい方がいたらピンとくるかも、ということで書いています。

  • 特定のメソッドのサンプルコードが Ruby の rdoc にあるけど rurema にないということをファイル名やファイル内の構造から特定可能
  • rurema でメソッドのサンプルコードを挿入する位置を特定可能

この2つを満たすなら、 rdoc から rurema にサンプルコードを自動移植してプルリクエストを投げる、
ぐらいのところまで自動化が可能かもしれない、と思いますがいかがでしょうか?

ただ、実際に rdoc のコードが rurema のガイドラインに沿ったものかどうかはわからないと思うので、
自動でプルリクを投げたあとに人間が確認する、というようになるのではと想像しています。

実現可能性は

  • いけそう?
  • むりそう?
  • 調べないとわからない

どれでしょうか?

この件の答えがでるまでは、 rdoc にサンプルがなくて rurema にもないものを追加していきます。

@sho-h

This comment has been minimized.

Show comment
Hide comment
@sho-h

sho-h Aug 26, 2017

Member

色々と入り乱れる感じになってきたので、何を作業したら終わりかをわかりやすくするために分けれるものはどんどんIssueをわけたくなってきました。

ガイドラインの修正

#523 を作りました。

Member

sho-h commented Aug 26, 2017

色々と入り乱れる感じになってきたので、何を作業したら終わりかをわかりやすくするために分けれるものはどんどんIssueをわけたくなってきました。

ガイドラインの修正

#523 を作りました。

@tbpgr

This comment has been minimized.

Show comment
Hide comment
@tbpgr

tbpgr Aug 26, 2017

Contributor

別Issue化ありがとうございます!

現状整理

Contributor

tbpgr commented Aug 26, 2017

別Issue化ありがとうございます!

現状整理

@ma2gedev

This comment has been minimized.

Show comment
Hide comment
@ma2gedev

ma2gedev Oct 18, 2018

ARGF 担当したいです

ma2gedev commented Oct 18, 2018

ARGF 担当したいです

@ma2gedev

This comment has been minimized.

Show comment
Hide comment
@ma2gedev

ma2gedev Oct 18, 2018

と思ったのですが、Obsolete なもの、IO クラス側にはサンプルがあるものばかりで、残っているものが inspect くらいでした。流石に inspect はサンプルコードなくて良いと思うので、一旦担当できそうなものを探し直します。
オススメとかあったら教えてください。

ma2gedev commented Oct 18, 2018

と思ったのですが、Obsolete なもの、IO クラス側にはサンプルがあるものばかりで、残っているものが inspect くらいでした。流石に inspect はサンプルコードなくて良いと思うので、一旦担当できそうなものを探し直します。
オススメとかあったら教えてください。

@tbpgr

This comment has been minimized.

Show comment
Hide comment
@tbpgr

tbpgr Oct 18, 2018

Contributor

@ma2gedev 参加ありがとうございます 😄

  • encoding 関連
  • process 関連

がけっこう残ってるので、そのへんいけそうだと嬉しいです。
その他だと、私以外の方が pull req 出して指摘をもらったあと手が止まっているやつがけっこうあるので、一言 pull req に巻取りのコメントしてからその続き、とかも助かります。

または、現在プルリクがでてなくて競合して無さそうなクラスを一つずつ選んで、シンタックスハイライトを有効にするというタスクもあります。

例えば、 Array だと、

  • assoc(key) は旧記法(ハイライトなし)
  • bsearch_index はハイライトあり

です。

これ以外がよければ標準添付ライブラリから見繕うので、声かけてください。

補足

サンプルが不要なやつは、目印として noexample をつけてます。
↓ noexample の例

https://github.com/rurema/doctree/pull/1415/files

Contributor

tbpgr commented Oct 18, 2018

@ma2gedev 参加ありがとうございます 😄

  • encoding 関連
  • process 関連

がけっこう残ってるので、そのへんいけそうだと嬉しいです。
その他だと、私以外の方が pull req 出して指摘をもらったあと手が止まっているやつがけっこうあるので、一言 pull req に巻取りのコメントしてからその続き、とかも助かります。

または、現在プルリクがでてなくて競合して無さそうなクラスを一つずつ選んで、シンタックスハイライトを有効にするというタスクもあります。

例えば、 Array だと、

  • assoc(key) は旧記法(ハイライトなし)
  • bsearch_index はハイライトあり

です。

これ以外がよければ標準添付ライブラリから見繕うので、声かけてください。

補足

サンプルが不要なやつは、目印として noexample をつけてます。
↓ noexample の例

https://github.com/rurema/doctree/pull/1415/files

@ma2gedev

This comment has been minimized.

Show comment
Hide comment
@ma2gedev

ma2gedev Oct 23, 2018

@tbpgr 見繕っていただきありがとうございます。では encoding を担当したいです。よろしくお願いします。

ma2gedev commented Oct 23, 2018

@tbpgr 見繕っていただきありがとうございます。では encoding を担当したいです。よろしくお願いします。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment