Make all inline docs proper YARD

[zverok]

...Many of documentational comments have "working yet outdated" style, which confuses novices. That should be fixed in according to YARD guides.

[Shekharrajak]

Do we need to change these kinds of comment syntax to YARD ?

[zverok]

Yep. It should be @option tag, in fact

[zverok]

Newly released yard-junk YARD docs checker tool says on current codebase:

Problems
--------
mistyped tags or other typos in documentation

lib/daru/category.rb:118: [UnknownParam] @param tag has unknown parameter name: *new_categories. Did you mean `new_categories`?
lib/daru/category.rb:175: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/category.rb:204: [UnknownParam] @param tag has unknown parameter name: *positions. Did you mean `positions`?
lib/daru/category.rb:231: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/category.rb:592: [UnknownParam] @param tag has unknown parameter name: arel
lib/daru/category.rb:666: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/category.rb:678: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/category.rb:697: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/category.rb:710: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/core/group_by.rb:206: [UnknownParam] @param tag has unknown parameter name: block
lib/daru/dataframe.rb:87: [UnknownTag] Unknown tag @params. Did you mean @param?
lib/daru/dataframe.rb:389: [UnknownParam] @param tag has unknown parameter name: *positions. Did you mean `positions`?
lib/daru/dataframe.rb:419: [UnknownTag] Unknown tag @vector
lib/daru/dataframe.rb:452: [UnknownParam] @param tag has unknown parameter name: *positions. Did you mean `positions`?
lib/daru/dataframe.rb:611: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/dataframe.rb:1046: [InvalidLink] Cannot resolve link to |row| from text: {|row| <a href=":age">row</a> > 0}
lib/daru/dataframe.rb:1142: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/dataframe.rb:1441: [UnknownParam] @param tag has unknown parameter name: idx
lib/daru/dataframe.rb:1527: [UnknownParam] @param tag has unknown parameter name: order
lib/daru/dataframe.rb:2049: [UnknownParam] @param tag has unknown parameter name: *names. Did you mean `names`?
lib/daru/date_time/index.rb:347: [UnknownParam] @param tag has unknown parameter name: Specify
lib/daru/date_time/offsets.rb:93: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/date_time/offsets.rb:93: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/index/categorical_index.rb:48: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/index/categorical_index.rb:148: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/index/categorical_index.rb:164: [UnknownParam] @param tag has unknown parameter name: positional. Did you mean `positions`?
lib/daru/index/categorical_index.rb:181: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/index/index.rb:93: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/index/index.rb:107: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/index/index.rb:139: [UnknownParam] @param tag has unknown parameter name: positional. Did you mean `positions`?
lib/daru/index/index.rb:221: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/index/index.rb:261: [UnknownParam] @param tag has unknown parameter name: input_indexes
lib/daru/index/multi_index.rb:155: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?
lib/daru/index/multi_index.rb:180: [UnknownParam] @param tag has unknown parameter name: positional. Did you mean `positions`?
lib/daru/io/io.rb:113: [UnknownParam] @param tag has unknown parameter name: dbh. Did you mean `db`?
lib/daru/maths/statistics/dataframe.rb:46: [UnknownParam] @param tag has unknown parameter name: max_lags
lib/daru/maths/statistics/dataframe.rb:50: [UnknownParam] @param tag has unknown parameter name: wilder
lib/daru/maths/statistics/dataframe.rb:72: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/dataframe.rb:72: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/dataframe.rb:72: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/dataframe.rb:72: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/dataframe.rb:72: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/dataframe.rb:72: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/dataframe.rb:72: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/dataframe.rb:72: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/vector.rb:573: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/vector.rb:573: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/vector.rb:573: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/vector.rb:573: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/vector.rb:573: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/vector.rb:573: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/vector.rb:573: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/maths/statistics/vector.rb:573: [UnknownParam] @param tag has unknown parameter name: n
lib/daru/vector.rb:231: [UnknownParam] @param tag has unknown parameter name: *positions. Did you mean `positions`?
lib/daru/vector.rb:255: [UnknownParam] @param tag has unknown parameter name: *positions. Did you mean `positions`?
lib/daru/vector.rb:388: [UnknownParam] @param tag has unknown parameter name: bool_arry. Did you mean `bool_array`?
lib/daru/vector.rb:392: [UnknownTag] Unknown tag @exmaple. Did you mean @example?
lib/daru/vector.rb:454: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/vector.rb:470: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/vector.rb:821: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/vector.rb:945: [UnknownTag] Unknown tag @params. Did you mean @param?
lib/daru/vector.rb:1185: [UnknownTag] Unknown tag @as_a
lib/daru/vector.rb:1188: [UnknownTag] Unknown tag @duplicate
lib/daru/vector.rb:1210: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/vector.rb:1232: [UnknownParam] @param tag has unknown parameter name: *values. Did you mean `values`?
lib/daru/vector.rb:1505: [UnknownTag] Unknown tag @dtype

0 failures, 66 problems (2 seconds to run)

Problems should be fixed, and yard-junk integrated into CI.

[athityakumar]

A quick aside : Should the YARD doc markup be set as markdown with redcarpet as provider? This is how it currently is setup in daru-io, and contributors would feel more at home by seeing the more familiar markdown comments.

[zverok]

Please don't touch this ticket, I am on it during specs refactoring. But answer to your question: It definitely would be markdown with kramdown provider (faster, more robust, has more features than redcarpet).