C++埋め込み数式

Question

C++コードの数式を文書化するためのベストプラクティスを知りたいと思います。

理想的には、方程式を直接コメントに書くことができるのは理想的ですが、人間が読める形式で書くことは実現できません。

私はLaTex、MathMLを見ていて、さまざまな視点から来ている多くの人々と作業するときに構文が複雑です（誰もが数学者ではありません）。この分野の経験があればコメントしてください。

例えば、ドキュメント化する必要のある各関数の外部HMLファイルに相互参照を追加していますが、維持するのは難しいです。私はDoxygenの式を試してみましたが、私たちの多くは構文が非常に複雑であることも発見しました。

\f[ 
    |I_2|=\left| \int_{0}^T \psi(t) 
      \left\{ 
       u(a,t)- 
       \int_{\gamma(t)}^a 
       \frac{d\theta}{k(\theta,t)} 
       \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi 
      \right\} dt 
      \right| 
    \f] 

Answer 1

すべての種類のシンボルを必要とする複雑な数式がある場合は、コードド​​キュメントではなく、関数ドキュメントに記述する方がよいでしょう。別個の文書である。

Answer 2

LaTeXの構文はあまり複雑ではなく、MathMLよりもはるかに人が読める（そして人が書けるように！）です（これは意見です）。少しの練習が助けになりますが、2時間以内に拾うことはありません。私の経験では、数学に富んだテキストをLaTeXに書き込むことは、最も便利な方法です。

あなたの数式がどれほど複雑かどうか、またはっきりとしたシンボルが必要かどうかによって、コードに数式を埋め込んでdoxygenを使うか、すでに述べたようにcreate別の書類。

Answer 3

「ASCII」アートはいつでも使用できます。あなたのエディタがUnicode（特に、UTF-8エンコード）をサポートしていれば、より良い結果が得られます。コードを実際に見ていると読みやすくなります。それを維持することは、TeXの構文よりも簡単ではないかもしれません。例えば。

//   │ ⌠T  {           } │ 
//   │ |  {   ⌠a  dθ ⌠θ     } │ 
// │ I │ = │ | ψ(t) { u(a,t) - |  ------ | c(ξ) u (ξ,t) dξ } dt │ 
// │ 2 │ │ |  {   ⌡γ(t) k(θ,t) ⌡a  t   } │ 
//   │ ⌡0  {           } │