"Documentation by paper"

[Robert Dewar]

Jamie Lokier wrote:
> Robert Dewar wrote:
> 
>>Now in the case of Java, there is no natural separation of specs and
>>implementation (for those of us of the Ada persuasion, this is one
>>of the serious deficiencies of the language). So you are most definitely
>>forced to use the approach of documentation extraction (assuming for
>>a moment that we are all agreeing on the merits of having the *source*
>>of the documentation reside with the source files).
> 
> 
> That _is_ the natural separation of specs and implementation in Java:
> the class source is the implementation (which you might not have
> access to), and the extracted documentation is the spec.
> 
> The mechanics of this can be seen as a way to synchronise text and
> declarations between the implementation and spec.  The fact that
> everyone does it in the direction class -> documentation is
> conventional, it's not a given.
> 
> In principle you could edit text in the spec (i.e. the documentation)
> and have changes applied automatically to the class source, but I've
> not heard of any editing environments that work that way.
> 
> (Ada and C imply _some_ duplication between the spec and
> implementation, don't they?  Every C type signature in a header file
> is repeated in the implementation; it's accepted practice that you
> have to edit both places to keep them synchronised).
> 
> 
>>I far prefer the fully documented header approach when it comes to C,
> 
> 
> I like full documented headers a lot.  The problem I find is what to
> put in the implementation file?  When editing something in a .c file,
> it's very helpful to have the textual comments which describe the
> interface near the source which implements them, usually as a comment
> just prior to the function it documents.
> 
> In my own programs, I tend to duplicate interface comments and whole
> file explanations: what's in the header file is repeated in the
> implementation file.  I hate the duplication, and the extra work
> required to maintain it, but find it makes the source that much
> clearer than a bunch of functions with no interface comments would be.
> 
> A tool which keeps the two synchronised might be helpful, but I
> haven't seen one or thought much about that.
> 
> -- Jamie