Robert Spier <[EMAIL PROTECTED]> 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.
>
>
> Which ones? emacs doesn't seem to do it by default.
>
>
> > And how can you get more explicit than XXX, anyway?
>
>
> Funny, but I still think TODO or FIXME makes more sense.
vim highlights all of XXX, TODO and FIXME by default (at least my
version does).
In terms of current popularity, there are 254 XXXs, 2 TODOs, and 6 FIXMEs
in the main bleadperl src. I guess XXX has the mindshare ;-)
> >>>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
>
>
> Which ones?
>
> > 2) Ease of parsing. (By our own tools that is, not by cc)
>
>
> int
> foo()
>
> is easier than
>
> int foo() ?
>
> By the tinyest amount. Is that really worth it for what is probably
> harder to human read.
grep '^Perl_' is very handy.
Also, my brain finds this harder to spot the function name in
struct Perl_foo_bar_baz* Perl_foo_bar_bazzer(foo f)
{
than this:
struct Perl_foo_bar_baz*
Perl_foo_bar_bazzer(foo f)
{
Personally I'd like to see all functions defined via a macro, eg
/* definer for 3-arg functions */
#define FUNC3(fn, ret, a1, a2, a3) ret fn(a1,a2,a3)
FUNC3(fn_name,
return_value*,
arg1type arg1,
arg2type arg2,
arg2type arg3)
{
....
which then allows for:
* easy manual or automated searching for fn defs
* automatic handling of all the pTHX_ stuff and/or any other arg or name
mangling we might need to do in the future
* easy automated extraction of info about fns
* possibly no need to have duplicate info in embed.pl or equivalent.
But I suspect this suggestion would go down like a lead ballon....
> >>> /*=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.
>
>
> Sure, POD everywhere, but lets make it POD6 with a little less
> whitespace and the other improvments that might come down the pipe.
> Limiting ourselves to POD5 will cause uglyness.
The syntax I suggested above is explicity not POD5 - the pod is started by
/*= at column 0, and is terminated by */ also at column 0, which involves
a lot less whitespace than POD5.
Also, the (TBC) indicated that this was by no means decided!
