Tex/LaTex formula tag

[spl1nes]

I've run quite often into the situation where it would be really nice to have LaTex support for a documentation. Even while I'm primarly a coder I find it much easier to understand a mathematical formula which a method tries to implement than looking at a bunch of code that in some cases is difficult to read do to numerical improvements.

Proposal

A tag like:

@formula x = {-b \pm \sqrt{b^2-4ac} \over 2a}

which get's rendered using LaTex and would be such a big help for many classes and functions I'm working on.

Cons:

• Maybe this is only of limited use since the person implementing the code would need to know LaTex and math/physic formula implementations aren't the forte of PHP
• This doesn't improve the readability in the source code since the strength of this would only unfold in the generated documentation
• Additional documentation loading times

Pros:

• Much easier to read in generated documentation
• This could lead to potential plugins for IDEs to also implementing this feature
• Enforces a standard of writing formulas since other formula formats will not get rendered

For the implementation existing libraries could be used in order to minimize the work that needs to be put into an implementation (e.g. https://github.com/mathjax/MathJax).

[mvriel]

Hello @spl1nes,

Can you provide me with a complete example of what you would like to document? I can imagine that it is actually more convenient to render the LaTex inline in the description as part of the text instead of as a separate tag.

It may even be more interesting to see how we can do this in a way that is supported by markdown / commonmark since this is actually a rendering issue and I see some discussion within commonmark about this: https://talk.commonmark.org/t/mathematics-extension/457/31

[spl1nes]

Some time ago I implemented my own documentation tool for php (of course much less sophisticated than phpDocumentor) but maybe this is still helpful for others.

Sample image of my own documation tool implementation:

And this is how the php documentation looks like responsible for the output:

    /**
     * Annual Percentage Yield
     *
     * The annual percentage yield (APY) calculates the yield taking compounding
     * into consideration.
     *
     * @latex  APY = \left(1+ \frac{r}{n}\right)^{n}-1
     *
     * @param float $r Stated annual interest rate
     * @param int   $n number of times compounded
     *
     * @return float
     *
     * @since  1.0.0
     */

Live view if required: http://docs.orange-management.de/phpOMS/Business/Finance/FinanceFormulas-getAnnualPercentageYield.html