On Thu, Aug 23, 2001 at 08:11:26PM -0400, Robert Spier wrote:
> How about something a little more explicit than XXX, like TODO or FIXME?
Some syntax-highlighting editors highlight "XXX". Let's use that feature.
And how can you get more explicit than XXX, anyway?
> > In function definitions, the name starts in column 0, with the
> > return type on the previous line
>
> Eww. Why do we want this again?
1) Dicky C compilers
2) Ease of parsing. (By our own tools that is, not by cc)
> > /*=for api apiname entityname[,entityname..] flags ....(TBC)....
> > comments....
> > */
>
> This is perl5ish syntax. Has there been thought about a different syntax here?
I'd prefer to go the other way, and just have POD everywhere. At the moment,
I'm spec'ing out the API for various functions by embedding POD in C comments;
I can then just run perldoc on a plain old C file, and I've got an API document.
% perldoc bytecode.c
BYTECODE.C(1) User Contributed Perl Documentation BYTECODE.C(1)
Bytecode Manipulation Functions
This file, "bytecode.c", contains all the functions
required by the core for the processing of the structure
of a bytecode file. It is not intended to understand the
bytecode stream itself, but merely dissect and reconstruct
data from the various other segments. See the parrotbyte
manpage for information about the structure of the frozen
bycode.
"check_magic"
Args: void** program_code
Check to see if the first "long" in *program_code
matches the Parrot magic number for bytecode; return 1
if so, and 0 if not. This function is expected to
advance the *program_code pointer beyond the magic num-
ber.
"read_constants_table"
Args: void** program_code
UNIMPLEMENTED.
Reads the constants segment from *program_code, and
creates the referenced constants. See the Constants
Segment entry in the parrotbyte manpage for the struc-
ture of the constants segment. Advances *program_code
beyond the constants segment.
...
Cool, eh?
Yeah, ideally the function declarations can be parsed to automatically
generate documentation about the return values and the arguments, but hey,
perldoc already exists, and I'm too lazy to write a sophisticated C
code parser. (Even with C::Scan.)
This may just be a temporary measure to help me spec out what functions
we need writing. I have a feeling that leaving big swathes of
implementation details in there as POD will clutter up the C file. But
once again, the beauty of doing it all in POD is that we have the tools
to extract it to another file if and when we need to.
Incidentally, things like the above will eventually turn into PIS
(Parrot Interface Specification) documents. I'll send some of these
out hopefully by the end of next week, and encourage people to pick
some functions and implement them. It's almost time to start coding,
people, almost.
Simon
