class Symbol のドキュメントが別のclassのものになっている

[ysakasin]

ruby/rdoc の不備なのか、 docs.ruby-lang.org の不備なのかわからなかったので、とりあえずこちらに報告します。

問題点

class Symbol のドキュメントが別の class のものになっており、正しいドキュメントが表示されない。

https://docs.ruby-lang.org/en/2.4.0/Symbol.html → Bignumのドキュメント
https://docs.ruby-lang.org/en/trunk/Symbol.html → Integerのドキュメント

他の症状

検索時に２つ候補が出てくる。どちらをクリックしても、間違ったドキュメントの文面が出てくる

原因？

class Symbol のドキュメントは symbol.c ではなく string.c に記述されている。

https://github.com/ruby/ruby/blob/5d12e826475b859649f113638066b42f21b7784f/string.c#L9962

他のドキュメントサイト

ruby-docでは正しいドキュメントが表示できている
http://ruby-doc.org/core-2.4.2/Symbol.html

手元の Dash for macOS では正しいドキュメントが表示できている

[okkez]

たしかにおかしいですね。タイトルはSymbolなのに中身がBignumやIntegerになっていますね。

@sho-h チェックしてもらってもいいでしょうか？

[sho-h]

@okkez はいー。

@NKMR6194 大変有益な切り分け情報含めありがとうございます！

#36 で作業中のvagrant環境で生成する分には同じ状態になりました。とりあえず 5730273 の修正の影響か気になったのでそれだけrevertして生成しましたが同じ状態でした。

教えていただいてる切り分けの結果からは有り得なさそうですが、document-classが間違ってるものはなかったです(確認したのはtrunkのみ)。

$ find . -type f | xargs grep -i 'document-class: symbol'
(string.cが引っかかるが、Symbolの定義はstring.cにあるので問題ない)

ruby-doc.orgの生成方法がわかるようなら、後でRakefileのrdoc:en/<ver>タスクと比較してみたいと思います。あとrdocだけ更新して直るとかであれば調査は途中でも一旦適用することを提案するかもしれません。

[ysakasin]

下記のように実行したところ、期待する内容の Symbol.html が生成されました

bundle exec rake source:2.4.0
bundle exec rake rdoc:en/2.4.0

ログ

[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ bundle exec rake source:2.4.0
git clone --depth=1 --branch=ruby_2_4 git://github.com/ruby/ruby.git sources/2.4.0
Cloning into 'sources/2.4.0'...
remote: Counting objects: 3771, done.
remote: Compressing objects: 100% (3484/3484), done.
remote: Total 3771 (delta 167), reused 1334 (delta 116), pack-reused 0
Receiving objects: 100% (3771/3771), 10.87 MiB | 5.44 MiB/s, done.
Resolving deltas: 100% (167/167), done.
[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ bundle exec rake rdoc:en/2.4.0
Parsing sources...
100% [879/879]  sources/2.4.0/vsnprintf.c                                                                           

Generating Darkfish format into /Users/yasuhiro/src/docs.ruby-lang.org/2.4.0...

  Files:        879

  Classes:     1311 ( 548 undocumented)
  Modules:      271 ( 110 undocumented)
  Constants:   1271 ( 530 undocumented)
  Attributes:  1053 ( 247 undocumented)
  Methods:     9852 (2103 undocumented)

  Total:      13758 (3538 undocumented)
   74.28% documented

  Elapsed: 215.1s
[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ sed -n 314,319p 2.4.0/Symbol.html 
          <p>Compares <code>symbol</code> with <code>other_symbol</code> after calling
<a href="Symbol.html#method-i-to_s">to_s</a> on each of the symbols.
Returns -1, 0, +1 or nil depending on whether <code>symbol</code> is less
than, equal to, or greater than <code>other_symbol</code>.</p>

<pre>+nil+ is returned if the two values are incomparable.</pre>

[ysakasin]

bundle exec rake source:2.4.0
bundle exec rake compile:2.4.0
bundle exec rake rdoc:en/2.4.0

の順でも正しい Symbol.html が得られました

ログ

[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ bundle exec rake source:2.4.0
git clone --depth=1 --branch=ruby_2_4 git://github.com/ruby/ruby.git sources/2.4.0
Cloning into 'sources/2.4.0'...
remote: Counting objects: 3771, done.
remote: Compressing objects: 100% (3484/3484), done.
remote: Total 3771 (delta 167), reused 1334 (delta 116), pack-reused 0
Receiving objects: 100% (3771/3771), 10.87 MiB | 453.00 KiB/s, done.
Resolving deltas: 100% (167/167), done.
[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ bundle exec rake compile:2.4.0
（略）
compiling ./enc/trans/single_byte.c
linking transcoder single_byte.bundle
compiling ./enc/trans/utf8_mac.c
linking transcoder utf8_mac.bundle
compiling ./enc/trans/utf_16_32.c
linking transcoder utf_16_32.bundle
making encs
make[1]: Nothing to be done for `encs'.
Generating RDoc documentation
Parsing sources...
100% [887/887]  vsnprintf.c                                                                            

Generating RI format into /Users/yasuhiro/src/docs.ruby-lang.org/sources/2.4.0/.ext/rdoc...

  Files:        887

  Classes:     1311 ( 548 undocumented)
  Modules:      274 ( 110 undocumented)
  Constants:   2141 ( 559 undocumented)
  Attributes:  1053 ( 247 undocumented)
  Methods:     9830 (2099 undocumented)

  Total:      14609 (3563 undocumented)
   75.61% documented

  Elapsed: 65.1s

[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ bundle exec rake rdoc:en/2.4.0
Parsing sources...
100% [887/887]  sources/2.4.0/vsnprintf.c                                                                           

Generating Darkfish format into /Users/yasuhiro/src/docs.ruby-lang.org/2.4.0...

  Files:        887

  Classes:     1311 ( 548 undocumented)
  Modules:      273 ( 110 undocumented)
  Constants:   2141 ( 559 undocumented)
  Attributes:  1053 ( 247 undocumented)
  Methods:     9866 (2105 undocumented)

  Total:      14644 (3569 undocumented)
   75.63% documented

  Elapsed: 208.6s

[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ sed -n 314,319p 2.4.0/Symbol.html
          <p>Compares <code>symbol</code> with <code>other_symbol</code> after calling
<a href="Symbol.html#method-i-to_s">to_s</a> on each of the symbols.
Returns -1, 0, +1 or nil depending on whether <code>symbol</code> is less
than, equal to, or greater than <code>other_symbol</code>.</p>

<pre>+nil+ is returned if the two values are incomparable.</pre>

[sho-h]

@NKMR6194 おぉ、助かります！ちなみにですがこの時のRubyとrdocのバージョン教えていただいていいですか？

[ysakasin]

@sho-h 以下の通りです

[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ ruby --version
ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-darwin16]
[sakasin@mac ~/src/docs.ruby-lang.org] (master=)$ bundle exec rdoc --version
5.1.0

[ysakasin]

compile時にriを生成していたので気になって見てみたのですが、ヘンテコなことになっていました。

Integer と BigDecimal のドキュメントが含まれています。

= Symbol < Object

------------------------------------------------------------------------------
= Includes:
Comparable (from
/Users/sakasin/src/docs.ruby-lang.org/sources/2.4.0/.ext/rdoc)

(from /Users/sakasin/src/docs.ruby-lang.org/sources/2.4.0/.ext/rdoc)
------------------------------------------------------------------------------

Symbol objects represent names and some strings inside the Ruby interpreter.
They are generated using the :name and :"string" literals syntax, and by the
various to_sym methods. The same Symbol object will be created for a given
name or string for the duration of a program's execution, regardless of the
context or meaning of that name. Thus if Fred is a constant in one context, a
method in another, and a class in a third, the Symbol :Fred will be the same
object in all three contexts.

  module One
    class Fred
    end
    $f1 = :Fred
  end
  module Two
    Fred = 1
    $f2 = :Fred
  end
  def Fred()
  end
  $f3 = :Fred
  $f1.object_id   #=> 2514190
  $f2.object_id   #=> 2514190
  $f3.object_id   #=> 2514190

BigDecimal extends the native Integer class to provide the #to_d method.

When you require the BigDecimal library in your application, this method will
be available on Integer objects.

Add double dispatch to Integer

When mathn is required, Integer's division is enhanced to return more precise
values from mathematical expressions.


  2/3*3  # => 0
  require 'mathn'
  2/3*3  # => 2

  (2**72) / ((2**70) * 3)  # => 4/3



Holds Integer values.  You cannot add a singleton method to an Integer. Any
attempt to add a singleton method to an Integer object will raise a TypeError.
------------------------------------------------------------------------------
= Constants:

GMP_VERSION:
  The version of loaded GMP.



= Class methods:

  all_symbols, each_prime, from_prime_division, json_create

= Instance methods:

  %, &, *, **, +, -, -@, /, <, <<, <=, <=>, ==, ===, =~, >, >=, >>, [], ^,
  abs, as_json, bit_length, capitalize, casecmp, casecmp?, ceil, chr, coerce,
  dclone, denominator, digits, div, divmod, downcase, downto, empty?,
  encoding, even?, fdiv, floor, gcd, gcdlcm, id2name, inspect, integer?,
  intern, lcm, length, magnitude, match, match?, modulo, next, numerator,
  odd?, ord, pred, prime?, prime_division, rationalize, remainder, round,
  size, slice, succ, swapcase, times, to_bn, to_d, to_f, to_i, to_int,
  to_json, to_proc, to_r, to_s, to_sym, truncate, upcase, upto, |, ~

[sho-h]

ありがとうございます！riの方はBigDecimal辺りが表示されてそうですね。うーん...

実サーバ上のRubyが2.3.3なので、以下のようにしてみると、手元では普通に生成されますが、Vagrant環境上ではそうではないですね...

local$ rbenv global 2.3.3
local$ bundle exec rdoc -v
5.1.0
local$ bundle exec rake source:2.4.0
local$ bundle exec rake rdoc:en/2.4.0
(Symbol.htmlが正常)

vagrant$ ruby -v
ruby 2.3.3p222 (2016-11-21) [x86_64-linux-gnu]
vagrant$ bundle exec rdoc -v
5.1.0
vagrant$ bundle exec rake source:2.4.0
vagrant$ bundle exec rake rdoc:en/2.4.0
(Symbol.htmlが異常)

vagrant環境の/var/www/docs.ruby-lang.org/revisions.logを見るに、1488692(本日時点では最新) のため、localとvagrantに差異はないはず...。

[ysakasin]

bundle exec rake rdoc を実行して中断した後に bundle exec rake rdoc:en/trunk したところ不正な Symbol.html がローカルでも再現しました

おそらく条件は 「 source 以下に複数のソースがあって、それらがコンパイルされていること」 のように思えます。

複数 source があるだけだと再現しませんでした。

また、trunkと2.4.0のリポジトリのみがsourceにあり、どちらもコンパイルされている状態では bundle exec rake rdoc:en/trunk のみが不正なSymbol.html を生成しました

[sho-h]

おぉ、再現すごい。

実は実機だとautoconfとbisonがなくてコンパイルの最初の方で失敗してるようなので、コンパイルは影響を及ぼせてなさそうです。「source 以下に複数のソースがあって、」の後はもう少し変わってくるかもしれません。

一方こちらでは、実機がDebianのため手元と実機で差分があるのかしら？とパッケージにあたってるパッチを見てみるなどしましたが、今のところ実りはありません。気になる修正はnormalized_file_listに対して以下のようなパッチがDebianパッケージのRubyのrdocに当たってるくらいでした。しかし、bundle installした方のrdocが使われますし、一応この修正を5.1.0のrdocに入れても動作に変化はありませんでした。(他の修正は関係ない気がする

--- ruby2.3-2.3.3.orig/lib/rdoc/rdoc.rb
+++ ruby2.3-2.3.3/lib/rdoc/rdoc.rb
@@ -321,7 +321,7 @@ option)
       end
     end

-    file_list.flatten
+    file_list.flatten.sort
   end

あとはrdocのバージョンを5.1から5.0にしても結果は変わりませんでした。

自分でも後で再現ためしてみます。

[sho-h]

しかし、時間がかかりそうですので、以下のような一次対応をお昼頃に取ろうかと思います。

• 直接再生成して置き換えるとか手元で生成して置き換える
• rdoc向けのcronを止める

[hsbt]

rdoc のバグかな? と思い issue で記録してました... ruby/rdoc#422

そもそもの理由は rdoc の可能性もあるので、何か発見したら教えてください。

[sho-h]

PRチャンスキタコレ！(報告了解ですー

上のDebianパッケージのみのrdoc 4.2.1にsortを追記するパッチ、rdocのmasterでは取り込まれてなさそうなのは気になってて(といっても同じ修正をしても改善しなかったので別の場所か問題が存在しないかですが)、rdocを真面目に追いかけないといけない気はしています。

[sho-h]

まとめて生成してみる。-> 確かに再現した。

$ (bundle インストールし直ししたりソース消してクリーンにする)
$ for version in 2.2.0 2.3.0 2.4.0 trunk; do
    bundle exec rake update:${version}
    bundle exec rake rdoc:clobber_en/${version}
    bundle exec rake rdoc:en/${version}
  done

あららと言うことで個別に。汚いけど以下のようにしてはソース消し消ししながらやったが結局どれかがうまく生成できてない感じなので置き直しもちょっと難しそう。

$ (クリーンに(ry
$ v=2.2.0 && bundle exec rake update:${v} && bundle exec rake rdoc:clobber_en/${v} && bundle exec rake rdoc:en/${v}
$ v=2.3.0 && bundle exec rake update:${v} && bundle exec rake rdoc:clobber_en/${v} && bundle exec rake rdoc:en/${v}
$ v=2.4.0 && bundle exec rake update:${v} && bundle exec rake rdoc:clobber_en/${v} && bundle exec rake rdoc:en/${v}
$ v=trunk && bundle exec rake update:${v} && bundle exec rake rdoc:clobber_en/${v} && bundle exec rake rdoc:en/${v}

条件として見てるものが置き換わってないだけで必ず何かが問題になるのかもしれない。