Documenting Mata code

[Niels Henrik Bruun]

Hi
Are there some tools to help documenting Mata code?
And are there some guidelines for doing so?

[Sergiy Radyakin]

StataCorp puts commentaries in the code and writes a manual on how to use it. This appears to be the best practice.
Some sources even include detailed references:

viewsource arfimaacf.mata

I think you will find some variation in styles by inspecting the several mata files shipped with Stata.
What documentation are you writing? For yourself? For another developer? For a customer? these may be different styles and different recommendations.

Best, Sergiy Radyakin

[Niels Henrik Bruun]

Hi Sergiy
Thank you for the link and recomendation.
I'll look into it.
And I agree that documentation depends on usage.
However in Python which I have been using for some years code documentation is integrated much more in the code with the possibility to integrate demos which also can serve as a sort of unit testing with the package docutils. And hence there are some recomendations for writing good documentation.

So I was just wandering whether there were guidelines for this wrt Mata.
I'll use the Mata code from Stata as an inspiration.
Again thank you very much

[Maarten Buis]

You can have worked examples in your help-files, see for example the helpfile for betafit. There there are examples, plus a link (click here to run) that will run the example code. Basically, that link will run an .ado file that mimics the output that would happen if you typed those commands command window. So the betafit package also contains an betafit_ex.ado file that runs the examples.

However, for code testing I would write dedicated certification scripts, see: http://www.stata-journal.com/article...article=pr0001. The examples in my help-files should run without error, but that alone is not enough for me to be conficent about my code.

[Niels Henrik Bruun]

Hi Maarten
Thank you very much for the link to an very inspiring article. And of course your comments on documentation.
I will certainly try this in my future developing.

But I also notice that this is mainly used wrt Stata.
I'm not saying that it can't be used with Mata, but Mata is a more proper programming language than Stata, which can be used for scripting as well.
Being a programming laguage it opens up for integrating code and documentation much like eg in Python.

If the tools are there and you twist your code a little it is possible to do a lot of testing, code writing and documentation in 1 document with the possibility of extraction of documentation and on the fly code testing. This test will of course not cover all, but you will catch a lot of errors before going public.

To me most code development should be in Mata using Stata mainly as user interface. Others might disagree on that
But that is my reason for asking.

Thank you all again, I've learned a lot