rw <richard.weinber...@gmail.com> writes: > some c programs use comments like /*@out@*/ or /*@null@*/. > what is the purpose of these comments? > are they some magic compiler keywords?
No, they are magic comments for software that generates API documentation from source code comments.
On 26 Sep., 23:01, Dag-Erling Smørgrav <d...@des.no> wrote:
> No, they are magic comments for software that generates API > documentation from source code comments.
which documentation software is using such comments? where are these magic keywords defined?
i saw /*@out@*/ for the first time in the qmail-1.03 source. the keyword is only used 4 times in 15k lines of source. i don't really think that djb used them for automatic documentation.
> what is the purpose of these comments? > are they some magic compiler keywords?
> thanks, > //richard
Those are annotations that could be there for documentation purposes or even for the compiler, although in comments makes that unlikely.
Microsoft introduced such comments with __out and __null to tell the compiler specific characteristics of a variable. Those are expanded into __declspec(...) constructs if my memory doesn't mislead me.
GNU uses a completely different syntax with __attribute__() to tell similar things;
The lack of a standard for those associations makes the code that uses them completely unportable. Other schemas are "special" comments where a sequence of /*@ introduces them, and a corresponding sequence closes them. Lclint used a schema like this to pass more information about a variable like if it can be NULL or in a parameter to specify that it is an output parameter or an input parameter.
rw <richard.weinber...@gmail.com> writes: > Dag-Erling Smørgrav <d...@des.no> writes: > > No, they are magic comments for software that generates API > > documentation from source code comments. > which documentation software is using such comments?
I was going to say "doxygen", but actually, after a closer look, I think they're intended as hints to a static code analysis tool, not for documentation.
In article <h9m53q$gc...@aioe.org>, jacob navia <ja...@nospam.org> wrote:
> The lack of a standard for those associations makes the code that > uses them completely unportable. Other schemas are "special" > comments where a sequence of /*@ introduces them, and a corresponding > sequence closes them. Lclint used a schema like this to pass more > information about a variable like if it can be NULL or in a > parameter to specify that it is an output parameter or an input > parameter.
Caduceus uses annotations with comments that start with /*@. For instance:
> what is the purpose of these comments? are they some magic compiler > keywords?
Those are clearly http://www.splint.org annotations which inform the Splint static analysis C code checker of the intentions of your declarations, so that it may check that references and implementations of those declarations conform to your stated intention.
As such they are not, nor will they ever be, part of the C standard. And hence are inappropriate for this particular forum.
Though there is an interesting overlap between such modern C keywords like const, volatile, restrict and some of the splint annotations. If the C standard committee were to ever say, "Gee, const, volatile, restrict were handy... I wonder whether there is anything else useful we could on this front?" then they could do worse than to plunder splint's annotations and gcc's attributes. A combination of some of those could really be useful.
/*@null*@/ for example denotes a pointer that may be null, and hence _must_ be checked before dereferencing (the implicit assumption is that it is non-null and will warn if a possibly null value is assigned to it.
/*@out@*/ Splint detects instances where the value of a location is used before it is defined. Splint does not report an error when a pointer to allocated but undefined storage is passed as an out parameter. Within the body of a function, Splint will assume an out parameter is allocated but not necessarily bound to a value, so an error is reported if its value is used before it is defined.
> Though there is an interesting overlap between such modern C keywords > like const, volatile, restrict and some of the splint annotations. If the > C standard committee were to ever say, "Gee, const, volatile, restrict > were handy... I wonder whether there is anything else useful we could on > this front?" then they could do worse than to plunder splint's > annotations and gcc's attributes. A combination of some of those could > really be useful.
Due to lack of standard notation, we see two different notations develop:
__attribute__() // gcc and __declspec() // Microsoft
to name the two biggest ones. There are zillion others...
It would be really a good idea to standardise this to make those annotations portable...
In any case C99 added the notation
int foo(SomeType arg[static 1]);
for arguments that can't be NULL, but it wasn't advertised as such and few people use it... Obviously that would not work fo arguments that CAN be NULL.
Great to see this is being worked on. I particularly like the concept of the "owner" annotation. That could be an immensely powerful tool to cleaning up dodgy design in large systems.
Personally I'm not fussed by the choice of syntax, any _one_ syntax will do.
I was somewhat underwhelmed by the initial list of proposed annotations. (noreturn, deprecated, warn_if_unused).
I feel the gcc'ish "const" and "pure" annotations, especially if they were checked and enforced by the compiler, provide powerful documentation of a C declarations intent. (Similar to, but in some ways more powerful than, the C++ "const" methods.)
Also of immense practical use, especially in the embedded systems development domain, are the packed and alignment attributes.
|
