"Yannick Duch�ne (Hibou57)" wrote in message news:op.vsgh49tfule2fv@index.ici... >Le Wed, 16 Mar 2011 22:51:05 +0100, Randy Brukardt 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.