関数リファレンスの書き方

M5StickCの日本語リファレンスを書いていますが、なかなか進まない。。。

新しい機能を調べるのが楽しいので、画面関連のリファレンス書くのが面倒になるんですよね。

はじめはMarkdownで手書き

現在はmkdocsで公開しているので、内部はMarkdown形式で書いています。最初にフォーマット決めて、手書きしていたのですが、書いているうちにフォーマットを変更したくなりますが、過去分を書き換えるのが面倒になってきました。

そこで、とりあえずライブラリのヘッダファイルにDoxygen形式のコメントを追加して、がんばって変換しようと実験しました。

どんなエディタでもいいとは思うんですが、VSCodeだと引数とかを自動追加してくれなかったので、Eclipseを使っています。/**を追加して改行すればある程度は自動的にコメントを追加してくれるので便利になりました。

本当は定形で追加して欲しいコマンドもあるんですが、まあ手で追加しています。

直接はできませんでした。XMLに出力してから変換ツールで変換します。

しかしながらその変換結果はmkdocs向きじゃなかったので、自分でXMLをパースして変換するプログラムを作るはめになりました。

ただ、XML形式だとたぶん出力に対応していないデータがあったり、データの個数によって構造が変わったりするので、コメントの付け方と変換方法とかも合わせて作り変えないとだめな感じです。

XMLから変換したままのリファレンス部分と、手で書きたいところがあるので、最終的にmarkdown_includeを使って、リファレンス部分だけincludeすることで、いい感じに分離できました。

include用のフォルダをdocs配下以外に置いているので、ファイル更新しても自動更新かからないのはちょっと不便ですが、まあ許容範囲です。

とりあえず主要なところはコメント無しですが、関数だけは追加できました。ソースみていると、なんでこれ公開しているんだろうって公開変数とか、ちゃんと動いていない関数とかがあったりして、この辺が大陸系なんだろうなって思います。