Front page | perl.perl6.internals |
Postings from July 2002
I'm trying to pay attention to the difficulties I have understanding parrot so
I can give some decent n00b feedback before I know the code like the back of
my hand.
First, test_main.c is a totally non-obvious location for parrot.exe's main().
I dismissed it out of hand when I did grep ^main. I only believed it was real
when I looked at the linker arguments. Is there a reason for the test_
prefix? It's really misleading if you're actually using it.
I'm also a little disturbed by *everything* having Parrot_ in front of it.
Namespace friendliness is nice, but having the internal functions with the
same prefix as the embed.c functions is unkind. I'd like to see _Parrot_ or
Parrot__ for the internal functions (hell, just the opcodes) and Parrot_
reserved for the visible API. _Parrot_ would be better, since source grepping
for ^Parrot wouldn't list them. Grepping for ^Parrot_new (the first function
called in main(), and the first function anyone reading from the top would
search for) was painful.
There's no pointers between source and documentation. embed.c is a direct
implementation of embed.pod, but neither mentions the other. Any place
documentation and implementation exist, they should point to each other.
Until the documentation is good enough that you don't need to look at the
source to see how to use it, the documentation needs to give the location of
the source. :)
test_main.c and embed.c have no comments. They are the starting-point of the
parrot interpreter but there's no guidance as to where to go from there. In
the case of embed.c, I would definitely like to see each function specify
what files their implementation can be found. A gushing amount of inline
documentation would be good too, but even as little as this:
struct Parrot_Interp *
Parrot_new(void)
{
if (!world_inited) {
world_inited = 1;
init_world(); /* global_setup.c */
}
return make_interpreter(NO_FLAGS); /* interpreter.c */
}
I had to cut&paste&grep the source countless times to find anything.
A pointer from test_main.c to embed.c and embed.pod would've been helpful as
well.
What the heck is parrot.c doing empty? I expected it to have... something. I
don't know. Being empty is Wrong. I would've expected the functions which are
actually in embed.c to be in there ala. perl5's perl.c at least. If it's not
going to have source, it definitely needs a comment saying "this is not the
file you are looking for, see test_main.c and embed.c".
</nitpick>
I think that's all for today,
Ashley Winters
--
When you do the community's rewrite, try to remember most of us are idiots.
Thread Next