develooper Front page | perl.perl6.internals | Postings from July 2002

PARROT QUESTIONS: Use the source, Luke

Thread Next
From:
Ashley Winters
Date:
July 14, 2002 01:49
Subject:
PARROT QUESTIONS: Use the source, Luke
Message ID:
200207140849.17055.qaqortog@nwlink.com
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


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About