C++ Embedding Mathematical formulas [closed]

Question

I’d like to know the best practices for documenting Mathematical formulas in C++ code.

Ideally it could have been perfect to be able to write equations directly into comment but it’s not feasible to write them in a Human readable fashion.

I looked to LaTex, MathML and the syntax is complicated when working with many people coming from different horizons (not everyone is mathematician after all). If you have any experience on this area please comment.

For instance, I’m adding cross reference to external HML files in each function that needs to be documented, but it’s hard to maintain. I gave a try to Doxygen formulas and most of us found the syntax very complicated also.

  \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

You could always use "ASCII" art. If your editors support Unicode (particularly, UTF-8 encoded), all the better. It might be more readable when actually looking at the code. Though maintaining it may not be any easier than TeX syntax. E.g.

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