what is /*@out@*/?
rw
some c programs use comments like /*@out@*/ or /*@null@*/.
e.g: http://www.google.com/codesearch?hl=de&lr=&q=%22%2F*%40out%40*%2F%22+lang%3Ac&sbtn=Suche
what is the purpose of these comments?
are they some magic compiler keywords?
thanks,
//richard
Dag-Erling Smørgrav
> are they some magic compiler keywords?
No, they are magic comments for software that generates API
documentation from source code comments.
DES
--
Dag-Erling Smørgrav - d...@des.no
rw
> 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.
thanks,
//richard
jacob navia
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.
jacob
Dag-Erling Smørgrav
> 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.
Vincent Lefevre
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:
http://why.lri.fr/caduceus/examples/float/Malcolm.c
--
Vincent Lef�vre <vin...@vinc17.org> - Web: <http://www.vinc17.org/>
100% accessible validated (X)HTML - Blog: <http://www.vinc17.org/blog/>
Work: CR INRIA - computer arithmetic / Ar�naire project (LIP, ENS-Lyon)
Ike Naar
Dag-Erling Smørgrav <d...@des.no> wrote:
That seems correct. For instance, splint annotations look exactly like that.
John Carter
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.
jacob navia
>
> 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.
jacob navia
> John Carter a écrit :
> 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...
>
Well, in the most recent mailing apparently the committee is working
in this direction, see a paper by David Svoboda
John Carter
>> It would be really a good idea to standardise this to make those
>> annotations portable...
>>
>>
> Well, in the most recent mailing apparently the committee is working in
> this direction, see a paper by David Svoboda
>
> http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1403.pdf
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.