Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I have developed a few quantitative libraries in C# where it is important to understand not only the classic information that goes with the XMLDoc comments (which contains basic information with the method signature) but also the mathematical formulas being use within the methods.

Hence I would like to be able to include extended documentation with the code, which could contain, for example Latex formulas, graphs, and so on.

Do you think such information should be included in the API documentation?

Or should it be included in a dev blog for examples?

Are there common tools that are usually used for this kind of purposes?

share|improve this question
    
The extended logic, can it be understood in little pieces, on a method-by-method basis, or should the user have to read the complete explanation before diving into the API? –  FrustratedWithFormsDesigner Apr 5 '12 at 15:04
    
Actually, both. I would sometimes like to explain the user how he should use some classes together, maybe providing a class diagram and a few global examples. It should also be somewhere a beginner programmer could look at for example. –  SRKX Apr 5 '12 at 15:06
    
Blogs are nice for conversations and lousy for documentation. You absolutely want the version of the code and the version of the doc to be tightly sync'ed, and a blog post has a life cycle independent of the code's. –  Ross Patterson Apr 8 '12 at 1:52
add comment

5 Answers

As far as I'm concerned, the closer you keep documentation to the code, the more likely it is to be kept up to date and the more useful it is likely to be.

That's why I try to keep all documentation in the same repository as the code, even user manuals, and try to keep it in a plain text format that can be easily managed by a revision control system.

In-code documentation

It looks like you already have this one covered, but it is important to remember that actually using the documentation facilities in your chosen development environment (pydoc for python, javadoc in java or xml comments in C#) is the single most important documentation technique. They make it easy to write the documentation at the same time as writing the code.

If you rely on coming back and documenting things later, you may not get around to it, but if you do it as you are writing the code, then what needs to be documented will be fresh in your mind. C# even has the option to issue a compilation warning if the XML documentation is incomplete or inconsistent with the actual code.

Tests as documentation

Another important aspect is having good integration and unit tests.

Often documentation concentrates on what classes and methods do in isolation, skipping over how they are used together to solve your problem. Tests often put these into context by showing how they interact with each other.

Similarly, unit-tests often point out external dependencies explicitly through which things need to be Mocked out.

I also find that using Test-driven development I write software which is easier to use, because I'm using it right from the word go. With a good testing framework, making code easier to test and making it easy to use are often the same thing.

Higher level documentation

Finally there is what to do about system level, architectural, developer and possibly also end-user documentation. Many would advocate writing such documentation in a wiki or using Word or other word processor, but for me the best place for such documentation is also alongside the code, in a plain text format that is version control system friendly.

Just like with in-code documentation, if you store your higher level documentation in your code repository then you are more likely to keep it up to date. You also get the benefit that when you pull out version X.Y of the code, you also get version X.Y of the documentation. In addition, if you use a VCS friendly format, then it means that it is easy to branch, diff and merge, just like your code.

I quite like rst, as it is easy to produce both html pages and pdf documents from it, and is much friendlier than LaTeX, yet can still include LaTeX math expressions when you need them.

When writing highly mathematical code, I also find it useful to have a few wxmaxima documents in my project repository. Being plain text, these also branch, diff and merge nicely, but using a computer algebra system can help you consistency check your formulae as well as document them.

share|improve this answer
add comment

You can include such documentation within the XML comments, and generate LaTeX manuals, web pages and other documents from it using Doxygen. Use the <remarks> and <example> elements for the extended prose.

share|improve this answer
add comment

I would use external documentation if you need to include class diagrams, graphs, formulas, images, etc. to explain how your libraries work. Include this external documentation as part of your library releases in whatever format you deem appropriate (LaTeX or otherwise). You can refer to this document from your code if you wish (e.g. "See the "Readme" documentation for more information.").

share|improve this answer
2  
...or direct hyperlinks to the relevant parts, if possible. –  FrustratedWithFormsDesigner Apr 5 '12 at 15:25
add comment

The key, I believe, is consistency. If you've consistently annotated the methods with comments that can be extracted by e.g. Doxygen, it only makes sense to include the extended logic description there as well since that's where fellow developers are most likely to look. Suddenly pointing the developer to some other document seems unnecessary and will only confuse the developers.

However, if the description of the entire program is given elsewhere, then you should stick with that and give the extended logic description there.

share|improve this answer
add comment

If you feel that it is necessary to document the innards of a method in your API, then you probably haven't defined/modularized the interface very well.

A well written API shouldn't REQUIRE the programmer to understand how the internals work. Also, by unnecessarily documenting the way it works you are breaking the abstraction layer and locking yourself into a specific implementation, which is not good either.

share|improve this answer
3  
I completely disagree. For a quantitative API, the user needs to know what the underlying algorithm is in order to know whether the methods suits his needs or to be able to understand the output (think about optimization, numerical approximations and so on). –  SRKX Apr 5 '12 at 17:17
    
If that is necessary I'd suggest you need to release a library, open source solution instead of an API. –  JohnFx Apr 5 '12 at 18:30
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.