docs/book comments ch.4

Heiko heiko at hexco.de
Mon Feb 16 00:29:31 UTC 2009


Hi,

some comments from a nonnative speaker (beware!)

in the parrot book, chapter 4, section 'Subroutine Calls':
Wouldn't it be nice, if the above mentioned factorial example could
be recognized in the example

     ($I0, $I1) = 'fact'(count, product)

?

These things don't work for me here (distract a bit):
1. IMO the standard signature of a factorial function is something like
($I0) = 'fact'(count)
2. what is '$I1' there for?
3. what are the semantics of count, and product?
(ok I see, it is later obvious from the  implementation)

If you want to show multiple arguments you could choose some other
example function like min(imum), lcd (least common denominator), etc...

------
In section 'Subroutine Declarations', after '.param int c' example:

and optionally returns result output values

For me it is a bit unclear what happens:
The caller could or could not expect a return value/values.
The subroutine could or could not supply a return value/values.
What is the effect when the caller wants a return value and 
the subroutine does not provide one? In Perl 5 I get 'undef', which 
can be detected.

------
In section 'Optional Parameters', 4th paragraph
the list of positional parameters
instead of 
the list of postional parameters

-----
In section 'Sub PMCs', 2nd paragraph:
maybe
'you need to first select the namespace PMC'
instead of
'you need to first the the namespace PMC'

------
in the same section: maybe insert a new section for metadata-related stuff or an index entry? 
Then it could be easier referenced.

Also for me this is the first metadata structure that has no type information, worth mentioning?

------
In section 'Tailcalls', 2nd code example, subroutine add_two
in the first call to add_one the closing brace is missing at the end of the line


------
In section 'Creating and Using Continuations', end of 3rd paragraph
'notation'
instead of
'notaton'

------
In section 'Scope and HLLs', 2nd paragraph
'Parrot doesn't have any direct analog'
instead of
'Parrot does't have any direct analog'

Nested subroutines can also define a lexical variable with the same name as one from an outer level, 
thus 'shadowing' or 'hiding' the variable of an outer level.

Could this info be added?
-----
In section 'LexPad and LexInfo PMCs', 1st paragraph
'we already mentioned briefly'
instead of
'we already mentioned breifly'


and in the 5th paragraph
'there are a limited number of operations that you can call it with'
instead of
'there are a limited number of operations that you can call with it'

-----
in section 'Namespaces', 6th paragraph, last sentence:
'to keep alike things together'
instead of
'to keep like things together'

-----
Before section 'Calling Methods', I would like to read something 
about the concept of 'classes and objects'.
Because we just had a discussion about namespaces, and are now
going over to method calls without the knowledge of the data structure
they are invoked on in. I think the sequence 'namespace', 'class', 'method'
is a better structure to follow.

Also see section 'Defining Methods', 1st paragraph:
'inside a namespace named after the class they are a part of'
Here it would be good to have an impression of how a class is defined.


great text btw
greetings,
hexcoder



More information about the parrot-dev mailing list