search

kzrnm / ac-library-csharp

42 stars 5 forks source link

ドキュメント作成について #54

Open terry-u16 opened 4 years ago

terry-u16 commented 4 years ago

ある程度はXMLコメントで網羅されてはいるのですが、別途使用例等含めたドキュメントがあると親切なのかなと思います。

ディレクトリ構成等違うのでそのままとはいかないかと思いますが、参考までにJava版ACLでは各アルゴリズム・データ構造別にmarkdownでドキュメントを作成しているようです。 https://github.com/NASU41/AtCoderLibraryForJava

テスト作成やExpander実装に比べれば少し優先度は落ちるかと思いますが、ご意見頂ければ嬉しいです……！（投げっぱなしですみません。）

takytank commented 4 years ago

これは自分も欲しいなと思っていました。 XMLコメントをhelpファイルか何かに変換するのであればまだいいと思いますが、現状だと一覧性がよろしくないです。

また、 INumOperator など、本家C++のライブラリには無い部分の解説と使用例は書いておかないと、contributor以外の人には使い方が分からない可能性が高いのでは？と思っています。

terry-u16 commented 4 years ago

XMLコメントをhelpファイルか何かに変換するのであればまだいいと思いますが、現状だと一覧性がよろしくないです。

XMLコメントからの自動生成はアリかなと私も思っていました。（このあたり詳しくなく、具体的に何を使えば良いかはお恥ずかしながら分からないのですが……。） 加えて、典型的な使用例みたいなものも書いてあげると利用側としては取っかかりが付きやすいのかな、と思っています。一通り使用例を書くのはそれなりに大変ではありますけどね。

また、 INumOperator など、本家C++のライブラリには無い部分の解説と使用例は書いておかないと、contributor以外の人には使い方が分からない可能性が高いのでは？と思っています。

少なくとも、言語仕様等の理由でC++版から変更を入れているものは説明が必要そうですね（パッと思い浮かぶところでいうとModIntやセグ木周り等？）。C++版と全く同じように使えるところは最悪「C++版と同様です」で一旦切り抜けて、優先度を若干下げても良いのかもしれません。 一方でINumOperatorについてはラッパークラスが用意されている関係上、ひとまず置いておいても一般的な使用を行う上ではそこまで困らないと思われるので、優先度を下げても大丈夫かもしれませんね。

長々と書きましたが、開発側（という言葉は適切ではないかもしれませんが）の我々だけでは分からない面もあるので、利用者の皆さんのご意見もあればコメント頂ければ嬉しいです……！

key-moon commented 4 years ago

あったほうがありがたいのは確かだと思います。 最低限 INumOperator や IMod 等の独自インターフェイスや、高速化の為に従うべき Tips（AggressiveInlining や static にすることでの展開）などは書くべきだと思いました。 優先度は下がりますが、AtCoder 公式のドキュメントのように全てのコードの使用例を確認できるようになると嬉しいですね。また、さらに優先度が下がりますが、document comment を定数として解釈して HTML 作成時に埋め込めるようにすると嬉しいですね。（library checker の markdown と HTML の変換では、@{[filename].[variable]}で変数を外部から埋め込むことができます。）

terry-u16 commented 4 years ago

document comment を定数として解釈して HTML 作成時に埋め込めるようにすると嬉しいですね。（library checker の markdown と HTML の変換では、@{[filename].[variable]}で変数を外部から埋め込むことができます。）

なるほどそれは知りませんでした……。ac-libraryの方も同じような形を取っていますね。二度手間にならなくて済むのは嬉しいです。Document Comment自体は吐き出してしまえばただのXMLですし、やろうと思えばやれそうですね。

最終的にはHTMLが吐けると良さそうですが、体制整うまではdocument_jaのようなフォルダを切って、ac-libraryのようなファイル粒度でmarkdownとしてひとまず公開するのが良いのかなと思っています。まずはC++版にない独自仕様周りを……ということで、ModInt, IModあたりについて試しに書いてみます。

kzrnm commented 4 years ago

https://dotnet.github.io/docfx/ ドキュメント生成は DocFX が良いと思います。

terry-u16 commented 4 years ago

このあたり詳しくないので助かります。ありがとうございます！ こういったツールはAPIリファレンスの生成に活用してあげると良いのかな？と当初思っていましたが、別途書いたmarkdownなんかもGetting started的な項目として取り込めるようなので（認識合ってますかね？）、これで全部吐き出すのも良さそうですね。