documentation

[Marco Martin]

On Tuesday 05 August 2014, Aaron J. Seigo wrote:
> 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
> 	...
> */

wouldn't it allow also
License: aseigo_gpl, notmart_bsd

that would mix 2 licenses in the same file?

maybe something like
 MyModule 1.0 {
  License {
    license: GPLv2+
    ids: aseigo_gpl, notmart_gpl
  }

so it checks they are all the same?


-- 
Marco Martin