Because i’m a lazy programmer, I like things that save me time. I don’t like having to keep phpdocumentor/doxygen style code up to date with the actual code inside a function. Also, including a documentation compilation step in a build process is annoying, and phpdocumentor/doxygen don’t result in a clean data source of functionality metadata that I can produce my own documentation interfaces from.
So, I guess you could say that there are two main problems I see with a phpdocumentor/doxygen style approach. First, it’s duplication of information. Aside from the DRY (Don’t Repeat Yourself) principle, this is a step worse because you end up repeating the information at least twice, both in code and also in some separate documentation format. That’s annoying, and it will be easily skipped by programmers in search of quick fixes. Secondly, there’s no live source of trustworthy metadata data where one can get at it easily in a programmatic way, without a compilation step.
A good solution presents both a structured data source of documentation, and also avoids needless repetition of information between the code and the docs.
So, since documentation about functions and their parameters is simply metadata about the function, why not store the documentation in data structures within the function itself?
The way I started solving this problem by taking a page from a subset of a hardcore approach to programming called Design by Contract. I’d heard about it before just as a general concept while doing my time in an undergrad CECS program, but always figured that it was too serious to get into. It was really fun to recall this old foggy concept while I was deriving a pretty useful solution to the problem described above.
The entire goal is to convert function docs from these specialized comment markup formats into a machine-readable data structure inside of each function. One will need to define a standard data structure in which to store metadata about a function’s parameters. This will vary depending on the programming language’s embedded types and parameter semantics.
Once a structure is defined, then one can standardize a method of passing in a documentation request struct reference to each method, and when the method notices it, it can simply fill it with the doc metadata and skip the normal control flow for the function. It’s essentially the same as asking a function to describe itself.
Secondly, one can immediately go about enhancing the parameter data structure to include detailed information about each parameter’s type, expected inputs, etc. This information can doubly be taken advantage of by writing generalized validation routines that use this metadata about parameters. If you were going to write validation routines anyway, this saves you having to needlessly repeat that metadata within code.
Thirdly, one now not only has quick, programmatic (and realtime, not compiled) access to function definition metadata, but it’s also more or less in exact sync with the actual parameters it expects, and it also in a standardized data structure. So one can dynamically generate an entire interface for say, spelunking through an API, out of the simple presence of functions that know how to document themselves.
You do pay the price of some realtime overhead, but the very real benefits in maintainability and elegance far outweight that, in my opinion. The implementation of this general derivative concept is pretty academic if you understand all the nerdery above. The key thing to do is to just take a page from Design by Contract, and have your program know about itself, rather than hiding its metadata within invisible comments.