mruby、mruby/c（PicoRuby）のペリフェラルAPI共通規格のドキュメントを整備したい

memo.md

やりたいこと

• mruby、mruby/c（PicoRuby）のペリフェラルAPI共通規格のドキュメントを整備したい

ペリフェラルとは

• マイコンの入出力に関する各種の規格
• 今回の対象になりそうなのは、GPIO, ADC, I2C, API, UART, PWM

mruby、mruby/cの「共通規格」とは

• 軽量Rubyフォーラム（mrubyのメンテ主体）、九州工業大およびITOC（mruby/cのメンテ主体）の共同の取り組み
• マイコンでのRuby利用を促進するため、標準的なAPI規格を策定する（している）。そして公開したい（←これが重要）
• わたくしハスミは、mruby/cのメンテナのひとりとして関与している
• まつもとさんはあんまりマイコンに詳しくないので、基本的にはこちらに任せてくれている

現状どうなっているか

• 大まかな規格案はすでにある： https://github.com/hirohitoHigashi/mruby_io_class_study/
• それをPicoRubyの（RP2040用）ライブラリとして実装しつつある： https://github.com/picoruby/picoruby/tree/master/mrbgems （この中の/picoruby-(gpio|adc|i2c|spi|uart)/）

↑ここまでは関係者の共通認識です。

↓ここから下はわたくしの個人的な考えですが、このドキュメント計画をほかに強く駆動する人はいないし、前向きな提案はだいたい受け入れられるので、うまいことやっていきたいと思っています

成果物はどんなものか

• マイクロパイソン先輩みたいなウェッブページ （GPIOの例）https://docs.micropython.org/en/latest/library/machine.Pin.html
• このようなHTMLを簡単にメンテナンスできる仕組みをつくりたい
• デプロイ先はmrubyまたはmruby/cのGitHub Pagesあたりか？
• 英語だけでいいと思う

スケジュール

• ことしの8月くらいに世に出したい

どんな仕組みだとよいか。ここからは妄想

• RBSから自動生成する仕組みがほしい（そういえば大倉さんがどこかでそんな話をしていたような...？）
• RBSはこういう風に書いてます：https://github.com/picoruby/picoruby/blob/master/mrbgems/picoruby-gpio/sig/gpio.rbs
• もちろんこれだけだとドキュメント情報として足らないので、説明文をコメントに書いたりするのはやぶさかじゃない
• RBSに書いてある情報は、RBSだけで完結したい（コメント側に重複する情報を書きたくない）
• 「RBS + コメント情報」をYARD（以下、YARDをRDocに読み替えてもよいです）に変換するとか？（この辺テキトウに言ってます）
• そういう生成が難しければ、最初からYARDでもいい
• GitHub Actionsなどにより自動でデプロイされるとうれしい。それはそう
• 「何をもとに生成するか」という問題はある。いつまでもpicoruby-(gpio|adc|etc.)がリファレンス実装でありつづけるとは限らない。ただ、とりあえずは既存のpicoruby-gpioが元データでよいと思う

要するにこういう話かな？

• なるべくメンテナンスが楽な方法で、
• HTMLをどう生成するか、
• その実装をだれがやるのか

将来的な展開

• ここでは「マイコンペリフェラルのAPI」の話をしているが、もっと広げられる可能性がある
• mrubyとmruby/cとでは組み込みライブラリの仕様に大きな違いがあるので、それらのドキュメントもほしい（これ実は結構めんどうかもしれなくて、Matz謹製mrubyと言えどもCRubyの仕様との相違がわりとあり、正確にドキュメント化するのは工数がかかりそう。なのでこれはいまのとこスコープ外）

当面の進め方（案）

• 参加者をここで募る
• 基本的なアイデア出しもここ（またはmruby/cのSlack）でやる
• 早々に行き詰まると思う（確信）ので、
• オンラインで話す。そしてまた進め方を考える

大倉さんの取り組み

• プラグインシステムのドキュメント生成ツールをつくっている
• バックエンド：YARDプラグイン、RBSプラグインなど
• バックエンドが収集した情報を、共通の中間表現にコンパイルして（マージして）フロントエンドへ渡す
• フロントエンド：HTMLプラグイン、LSPプラグインなど
• バックエンドの実装イメージ https://gist.github.com/okuramasafumi/8dde6e4cbdf1e65cda4a904bbc9cc7cb
• コンセプト：型情報はRBSから持ってきて、そのほかの情報はYARDコメントからもってくる、でよい

それに対し、mruby(/c)ペリフェラルドキュメント側の事情

• ペリフェラルの実装はmrubyとmruby/cでそれぞれ作るし、なんならマイコンごとに作られるかもしれないので、.rbファイル側にドキュメント情報があるのは嫌だ
• RBSだけに寄せて一箇所で管理したい
• つまり、RBSにコメントを書くかたちでドキュメントの情報を充足させたい

とするならどうなるか

• SteepがもっているRBSパーサをハック？
• 読み捨てられているであろうRBS内コメント情報をどうにかして取得する？
• あるいは、RBSのコメント部分（およびその直下のクラス名／メソッド名の関連付け）だけを抜き出す独自パーサを書くか？

その他

• Stripeのドキュメントかっこいい https://stripe.com/docs/api