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