documentation

[Aaron J. Seigo]

Hi :)

So, documentation. That thing developers often don't write ;)

There are a few goals for documentation support in funq:

* make it easy to write _good_ documentation
* encourage standardized formatting
* give the developer good hints as to how well they are doing with docu

There are a few different types of documentation in scope:

* module licensing: who wrote it, what is the license, ...?
* module documentation: what does the module do? how should it be used?
* function documentation: what does a function do? parameters?

The idea is to create a documentation system that plugs into the compiler 
toolchain so that there is maximum opportunity to do useful, powerful things.

Examples:

For licensing .. this is generally the same for every file in a project. What 
changes, if anything, is the people who have contributed to that file. That 
information is often *wrong* in headers in C / C++ projects because it is a 
tedious, manual process. When someone's email changes it means changing it in 
many files (thank goodness for multi-file search and replace). So perhaps 
instead there should be a top-level file containing licensing entities like:

License {
	id: aseigo_gpl
	who: Aaron Seigo
	email: aseigo at kde.org
	license: GPLv2+
}

and then in a module:

MyModule 1.0 {

/*
	License: aseigo_gpl, notmart_gpl
	...
*/


When writing a function it would be nice to be able to pick between a couple 
standard forms of function documentation such as "functional overview" and 
"parameter-by-parameter description". The AST API should expose a way for a 
text editor / IDE to request the boilerplate for the current function for it 
to insert. So a simple editor macro could get you a good way to standardized 
documentation; it could even be used to drive a simple UI .. imagine an IDE 
where the documentation was not shown as plain text but as an editable form. 
(It would be saved as plain text, of course :)

This should also allow a project to be checked for licensing cleanliness. It 
would mean that when a file is copied from one project to another that the 
licensing entity would also need to be brought over separately, but entities 
w/out definition could be caught and reported as warnings / errors.


It should be possible to get warned when documentation no longer matches a 
function (or even better: automatically alter documentation as the function 
changes; e.g. if a parameter changes name, change the documentation to reflect 
this automatically).


It should be possible to request documentation coverage reports. These could 
include not only the raw numbers but even reinforcing feedback in the form of 
a star rating or points system to provide positive reinforcement to the 
developer for doing a good job.


Thoughts? Ideas?

I'm still looking for the exact syntax to use for documentation. It ought to 
be easily machine parseable without ambiguity, allow for reasonable amounts of 
formatting, referencing other functions, referencing parameters .. and be easy 
to learn. Prior art includes doxygen (not my favorite thing in the world, but 
ubiquitous), pydoc, perldoc ...

If anyone would like to work on defining the syntax,.... :) If not, I'll get 
to it once I have documented a few of the more "boring" pieces like operators 
and comprehensions ...

-- 
Aaron J. Seigo
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://kde.org/pipermail/funq-devel/attachments/20140805/8d309ac6/attachment.sig>