Re: AWS Coding Styles (and about boring plain-linear text files in the end)

["Randy Brukardt" <randy@rrsoftware.com>]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2614 bytes --]

"Yannick Duch�ne (Hibou57)" <yannick_duchene@yahoo.fr> wrote in message 
news:op.vsgh49tfule2fv@index.ici...
>Le Wed, 16 Mar 2011 22:51:05 +0100, Randy Brukardt <randy@rrsoftware.com>
a �crit:
>> Janus/Ada has used "@" as the conditional compilation character since it 
>> was
>> created. (It is either treated as a space or a comment symbol ("--")
>> depending on the compiler switches.) So you'll find lots of '@' in 
>> Janus/Ada
>> source code, and what follows it has little to do with annotations.
>
>What are your personal suggestions there ? Do you use any kind of helpers 
>to get human readable documentation texts and sources synchronized ? (this 
>is worded this way, with emphases on synchronization, because there is not 
>formally any requirement for this to be all written inside the source 
>only).

For Claw, we created a tool that processes the public specifications 
(including the comments) and turns them into HTML/RTF documentation. That 
documentation has an intermediate representation that can be hand-edited (to 
improve the format of the comments -- they're marked up in a similar way to 
the way the !corrigendum sections are marked up in AIs -- what a surprise 
:-), and a mechanism to update the intermediate without clobbering the 
hand-edits.

It proved to be too complex in practice; I doubt I would use it again.

What I'd probably do today is define a documentation aspect (probably 
formatted in HTML) and make that an intergral part of the source code. That 
would take advantage of the permission added to Ada 2012 during yesterday's 
phone meeting (how's that for up-to-the minute changes??) for compiler 
writer's to add implementation-defined aspects of their own design and 
syntax to Ada 2012.

Of course this requires getting support for that added to your favorite Ada 
compiler (I have a distinct advantage there); a tool to produce code without 
the aspect (so the code can be ported to another compiler) [also pretty 
easy, of course], and preferably some support in the IDE.

To do something portable, you'd have to do something similar in Ada 
comments. That means defining a special comment symbol to mark your 
formatted documentation, and again preferably some IDE support (especially 
so that the documentation doesn't overwhelm the code).

I don't think separate files are really practical, with the possible 
exception of something that is managed automatically by an IDE. It's just 
too hard to keep them in synch. (And of course, if you have to depend on IDE 
support, it will only work on that IDE.)

                                     Randy.