Author: chromatic
Date: Tue Jun 10 23:11:50 2008
New Revision: 28231
Modified:
trunk/docs/pdds/draft/pdd01_overview.pod
trunk/docs/pdds/draft/pdd04_datatypes.pod
trunk/docs/pdds/draft/pdd06_pasm.pod
trunk/docs/pdds/draft/pdd08_keys.pod
trunk/docs/pdds/draft/pdd11_extending.pod
trunk/docs/pdds/draft/pdd16_native_call.pod
trunk/docs/pdds/draft/pdd19_pir.pod
trunk/docs/pdds/draft/pdd29_compiler_tools.pod
trunk/docs/pdds/pdd09_gc.pod
trunk/docs/pdds/pdd17_pmc.pod
trunk/docs/pdds/pdd28_strings.pod
Log:
[PDDs] Cleaned up PDD formatting errors from the codingstd tests.
Modified: trunk/docs/pdds/draft/pdd01_overview.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd01_overview.pod (original)
+++ trunk/docs/pdds/draft/pdd01_overview.pod Tue Jun 10 23:11:50 2008
@@ -33,6 +33,8 @@
| Extensions |
+---------------------------------------------------+
+=head1 IMPLEMENTATION
+
=head2 Parser
While individual high-level languages may implement their own parser,
Modified: trunk/docs/pdds/draft/pdd04_datatypes.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd04_datatypes.pod (original)
+++ trunk/docs/pdds/draft/pdd04_datatypes.pod Tue Jun 10 23:11:50 2008
@@ -109,7 +109,7 @@
=item Version 1.4
Document basic PMC internals. Make clear the fact that the bigint/bignum
-description is still provisional. Other minor fixups to make the documentation
+description is still provisional. Other minor fixups to make the documentation
match reality.
=item Version 1.3
Modified: trunk/docs/pdds/draft/pdd06_pasm.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd06_pasm.pod (original)
+++ trunk/docs/pdds/draft/pdd06_pasm.pod Tue Jun 10 23:11:50 2008
@@ -28,29 +28,34 @@
<barney> Can we get rid of PASM ?
<spinclad> conversely, does PASM need to be kept up to date?
<allison> PASM is just a text form of PBC, so it should be kept
- <allison> are there specific PBC features that can't currently be
represented in PASM?
+ <allison> are there specific PBC features that can't currently be
+ represented in PASM?
<particle> besides hll and :outer?
<chromatic> :init
<mdiep> lexicals?
<chromatic> :vtable
- <mdiep> I'm a bit rusty, but anything that starts with a '.' or ':' is
suspect
+ <mdiep> I'm a bit rusty, but anything that starts with a '.' or ':'
+ is suspect
<allison> things that start with '.' are just directives to IMCC,
equally applicable to PASM and PIR
<mdiep> isn't PASM separate from IMCC?
<allison> mdiep: it used to be separate
- <mdiep> so to say that PASM can have directives is a major
architectural change
- <allison> perhaps the biggest thing we need is a definition of what PASM
actually is
+ <mdiep> so to say that PASM can have directives is a major
+ architectural change
+ <allison> perhaps the biggest thing we need is a definition of what PASM
+ actually is
<allison> the line has grown quite fuzzy over the years
<barney> PASM could be defined as stringified PBC
<particle> compilable stringified pbc
- <mdiep> it should be defined that way if we're going to call it
assembly.
- <allison> barney: that's the most likely direction, and if so, it has
some implications
- for how PASM behaves
+ <mdiep> it should be defined that way if we're going to call it
+ assembly.
+ <allison> barney: that's the most likely direction, and if so, it has
+ some implications for how PASM behaves
<particle> allison: which is what we want, anyway, right?
<allison> particle: yup
<barney> yes
- <particle> good, looks like we're in agreement and headed in the proper
direction on
- that topic.
+ <particle> good, looks like we're in agreement and headed in the proper
+ direction on that topic.
=back
@@ -1142,7 +1147,8 @@
=item * return is now ret
-=item * Added save and restore ops for saving and restoring individual
registers
+=item * Added save and restore ops for saving and restoring individual
+registers
=back
Modified: trunk/docs/pdds/draft/pdd08_keys.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd08_keys.pod (original)
+++ trunk/docs/pdds/draft/pdd08_keys.pod Tue Jun 10 23:11:50 2008
@@ -285,7 +285,7 @@
=back
-=head2 REFERENCES
+=head1 REFERENCES
To come.
Modified: trunk/docs/pdds/draft/pdd11_extending.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd11_extending.pod (original)
+++ trunk/docs/pdds/draft/pdd11_extending.pod Tue Jun 10 23:11:50 2008
@@ -32,7 +32,9 @@
functions may be added, and those described below may change or be removed.
You have been warned...
-=head1 API - Group 1: Internals-unaware functions
+=head1 IMPLEMENTATION
+
+=head2 API - Group 1: Internals-unaware functions
These functions are the ones that are largely unaware of the structure and
architecture of Parrot. They deal mainly in data as abstract entities, and
@@ -40,7 +42,7 @@
calls. This is sufficient for many extensions which act as black box
processing units and in turn treat Parrot itself as a black box.
-=head2 PMC access functions
+=head3 PMC access functions
The following functions are for storing and retrieving data inside PMCs. Note
that use of the _keyed functions with non-aggregate PMCs will generally just
@@ -139,7 +141,8 @@
Assign the passed-in pointer to the passed-in PMC.
-=item C<Parrot_PMC_set_pointer_intkey(interp, pmc, void *value, Parrot_Int
key)>
+=item C<Parrot_PMC_set_pointer_intkey(interp, pmc, void *value,
+Parrot_Int key)>
Keyed version of C<Parrot_PMC_set_pointer>. Assigns C<value> to the PMC stored
at element <key> of the passed-in PMC.
@@ -199,7 +202,7 @@
=back
-=head2 Creation and destruction
+=head3 Creation and destruction
Functions used to create and destroy PMCs, Parrot_Strings, etc.
@@ -268,7 +271,7 @@
=back
-=head2 Subroutine and method calls
+=head3 Subroutine and method calls
Functions to call Parrot subroutines and methods
@@ -288,7 +291,7 @@
=back
-=head1 API - Group 2: Internals aware
+=head2 API - Group 2: Internals aware
The internals-aware functions are for those extensions that need to query or
alter the state of Parrot's internals in some way.
Modified: trunk/docs/pdds/draft/pdd16_native_call.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd16_native_call.pod (original)
+++ trunk/docs/pdds/draft/pdd16_native_call.pod Tue Jun 10 23:11:50 2008
@@ -34,6 +34,8 @@
signature) the signature must be passed in when the linkage between the C
function and parrot is made.
+=head1 IMPLEMENTATION
+
=head2 Function signatures
The following list are the valid letters in the function signatures for
Modified: trunk/docs/pdds/draft/pdd19_pir.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd19_pir.pod (original)
+++ trunk/docs/pdds/draft/pdd19_pir.pod Tue Jun 10 23:11:50 2008
@@ -23,6 +23,8 @@
generated output from high-level language compilers, and for human use
developing core features and extensions for Parrot.
+=head1 IMPLEMENTATION
+
=head2 Basic Syntax
A valid PIR program consists of a sequence of statements, directives, comments
@@ -824,8 +826,10 @@
{{ NOTE: response to the question:
<pmichaud> I don't think that 'morph' as a method call is a good idea
- <pmichaud> we need something that says "assign to value" versus "assign
to container"
- <pmichaud> we can't eliminate the existing 'morph' opcode until we have a
replacement
+ <pmichaud> we need something that says "assign to value" versus
+ "assign to container"
+ <pmichaud> we can't eliminate the existing 'morph' opcode until we have a
+ replacement
}}
@@ -845,15 +849,15 @@
C<.include> directive occurs.
The include file is searched for in the current directory and in
-runtime/parrot/include, in that order. The first file of that name to
-be found is included.
+runtime/parrot/include, in that order. The first file of that name to be found
+is included.
-{{ Check the search order of the include directive and whether it's complete }}
+{{ Check the include directive's search order and whether it's complete }}
=item * C<.macro> <identifier> [<parameters>]
-The C<.macro> directive starts the definition of a macro named by the
-specified identifier. The optional parameter list is a comma-separated list of
+The C<.macro> directive starts the a macro definition named by the specified
+identifier. The optional parameter list is a comma-separated list of
identifiers, enclosed in parentheses. See C<.endm> for ending the macro
definition.
Modified: trunk/docs/pdds/draft/pdd29_compiler_tools.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd29_compiler_tools.pod (original)
+++ trunk/docs/pdds/draft/pdd29_compiler_tools.pod Tue Jun 10 23:11:50 2008
@@ -56,10 +56,9 @@
get started with the PCT.
The script is located in C<tools/dev/mk_language_shell.pl>.
-{{ Not sure whether the mk_language_shell.pl script should be mentioned long
term
- In a sense, this script can also be considered part of the parrot compiler
"tools",
- as it is used to create a compiler.
-}}
+{{ Not sure whether the mk_language_shell.pl script should be mentioned long
+term. In a sense, this script can also be considered part of the parrot
+compiler "tools", as it is used to create a compiler. }}
=head2 Parser Synopsis
Modified: trunk/docs/pdds/pdd09_gc.pod
==============================================================================
--- trunk/docs/pdds/pdd09_gc.pod (original)
+++ trunk/docs/pdds/pdd09_gc.pod Tue Jun 10 23:11:50 2008
@@ -421,7 +421,7 @@
{{DEPRECATION NOTE: finalize_gc_system used to be
de_init_gc_system.}}
-=item C<void (*init_pool) (Interp *, struct Small_Object_Pool *)>
+=item C<void (*init_pool) (Interp *, Small_Object_Pool *)>
A function to initialize the given pool. This function should set the
following object allocation functions for the given pool.
@@ -435,7 +435,7 @@
=over 4
-=item C<PObj * (*get_free_object) (Interp *, struct Small_Object_Pool*)>
+=item C<PObj * (*get_free_object) (Interp *, Small_Object_Pool*)>
Each header pool provides one function pointer to get a new object from that
pool. It should return one free object from the given pool (removing it from
@@ -443,15 +443,15 @@
used by the garbage collector itself. If the pool is a buffer header pool,
all other object memory is zeroed.
-=item C<void (*add_free_object) (Interp *, struct Small_Object_Pool *, PObj
*);>
+=item C<void (*add_free_object) (Interp *, Small_Object_Pool *, PObj *);>
Add a freed object to the pool's free list.
-=item C<void (*alloc_objects) (Interp *, struct Small_Object_Pool *);>
+=item C<void (*alloc_objects) (Interp *, Small_Object_Pool *);>
Initial allocation of objects for the pool.
-=item C<void (*more_objects) (Interp *, struct Small_Object_Pool *);>
+=item C<void (*more_objects) (Interp *, Small_Object_Pool *);>
Reallocation for additional objects. It has the same signature as
C<alloc_objects>, and in some GC cores the same function pointer is used for
Modified: trunk/docs/pdds/pdd17_pmc.pod
==============================================================================
--- trunk/docs/pdds/pdd17_pmc.pod (original)
+++ trunk/docs/pdds/pdd17_pmc.pod Tue Jun 10 23:11:50 2008
@@ -1512,7 +1512,9 @@
=item set_attr
- void set_attr(INTERP, PMC* self, INTVAL idx, PMC* value) [deprecated: See RT
#48585]
+ void set_attr(INTERP, PMC* self, INTVAL idx, PMC* value)
+ [deprecated: See RT #48585]
+
void set_attr_str(INTERP, PMC* self, STRING* idx, PMC* value)
Store an attribute value in the PMC (instance object).
@@ -1575,7 +1577,8 @@
=item add_vtable_override
- void add_vtable_override(INTERP, PMC* self, STRING* vtable_name, PMC*
sub_pmc)
+ void add_vtable_override(INTERP, PMC *self, STRING *vtable_name,
+ PMC *sub_pmc)
Add a vtable override to the PMC (class object).
Modified: trunk/docs/pdds/pdd28_strings.pod
==============================================================================
--- trunk/docs/pdds/pdd28_strings.pod (original)
+++ trunk/docs/pdds/pdd28_strings.pod Tue Jun 10 23:11:50 2008
@@ -279,10 +279,10 @@
A structure that holds the buffer for the string data and the size of the
buffer in bytes.
-{{NOTE: this is currently called "cache" for compatibility with PMC structures.
-As we move toward eliminating the cache from PMCs, we will flatten out this
+{{ NOTE: this is currently called "cache" for compatibility with PMC
+structures. As we eliminate the cache from PMCs, we will flatten out this
union value in the string structure to two members: a string buffer and the
-size of the buffer used.}}
+size of the buffer used. }}
=item flags
@@ -324,14 +324,13 @@
=item normalization
-What normalization form the string data is in, one of the 4 Unicode
-normalization forms or NFG. This structure stores information about the current
-normalization form, function pointers for composition and decomposition for the
-current normalization form, and a pointer to the grapheme table for NFG.
+What normalization form the string data is in, one of the four Unicode
+normalization forms or NFG. This structure stores the current normalization
+form, function pointers for composition and decomposition for the current
+normalization form, and a pointer to the grapheme table for NFG.
=back
-
{{DEPRECATION NOTE: the enum C<parrot_string_representation_t> will be removed
from the parrot string structure. It's been commented out for years.}}
@@ -381,21 +380,21 @@
=head3 Parrot_string_write_COW (was Parrot_unmake_COW)
-If the specified Parrot string is copy‐on‐write, copy the string value to a new
-string buffer and clear the copy-on-write flag.
+If the specified Parrot string is copy-on-write, copy the string's contents
+to a new string buffer and clear the copy-on-write flag.
=head3 Parrot_string_concat (was string_concat)
Concatenate two strings. Takes three arguments: two strings, and one integer
-value of flags. If both string arguments are null, returns a new string created
+value of flags. If both string arguments are null, return a new string created
according to the integer flags.
=head3 Parrot_string_append (was string_append)
Append one string to another and return the result. In the default case, the
-return value is the same as the first string argument (the argument is modified
-by the operation). If the first argument is COW or read-only, then the return
-value is a new string.
+return value is the same as the first string argument (modifying that argument
+in place). If the first argument is COW or read-only, then the return value is
+a new string.
=head3 Parrot_string_from_cstring (was string_from_cstring)
@@ -418,17 +417,17 @@
=head3 Parrot_string_new_init (was string_make_direct)
Returns a new string of the requested encoding, character set, and
-normalization form, initializing the string value to the value passed in. Takes
-5 arguments, a C string (C<char *>), an integer length of the string argument
-in bytes, and struct pointers for encoding, character set, and normalization
-form structs. If the C string (C<char *>) value is not passed, returns an empty
-string. If the encoding, character set, or normalization form are passed as
-null values, default values are used.
-
-{{NOTE: the crippled version of this function, C<string_make>, used to accept a
-string name for the character set. This behavior is no longer supported, but
-C<Parrot_find_encoding> and C<Parrot_find_charset> can be called to look up the
-encoding or character set structs.}}
+normalization form, initializing the string value to the value passed in. The
+five arguments are a C string (C<char *>), an integer length of the string
+argument in bytes, and struct pointers for encoding, character set, and
+normalization form structs. If the C string (C<char *>) value is not passed,
+returns an empty string. If the encoding, character set, or normalization form
+are passed as null values, default values are used.
+
+{{ NOTE: the crippled version of this function, C<string_make>, used to accept
+a string name for the character set. This behavior is no longer supported, but
+C<Parrot_find_encoding> and C<Parrot_find_charset> can look up the encoding or
+character set structs. }}
=head3 Parrot_constant_string_new (was const_string)
@@ -440,8 +439,8 @@
Resize the string buffer of the given string adding the number of bytes passed
in the integer argument. If the argument is negative, remove the given number
-of bytes. Throws an exception if shrinking the string buffer size will truncate
-the string (if C<strlen> will be longer than C<buflen>).
+of bytes. Throws an exception if shrinking the string buffer size will
+truncate the string (if C<strlen> will be longer than C<buflen>).
=head3 Parrot_string_length (was string_compute_strlen)
@@ -457,8 +456,8 @@
Returns the number of bytes in the string. The character width of
variable-width encodings is ignored. Combining characters are not treated any
-differently than other characters. This is equivalent to directly accessing the
-C<strlen> member of the C<STRING> struct.
+differently than other characters. This is equivalent to accessing the
+C<strlen> member of the C<STRING> struct directly.
=head3 Parrot_string_index (was string_index)
@@ -468,17 +467,17 @@
=head3 Parrot_string_grapheme_index
-Returns the grapheme at the specified index (the Nth grapheme from the start of
-the string). Groups of combining characters count as a single grapheme, so this
+Returns the grapheme at the given index (the Nth grapheme from the string's
+start). Groups of combining characters count as a single grapheme, so this
function may return multiple characters.
=head3 Parrot_string_find_substr (was string_str_index)
Search for a given substring within a string. If it's found, return an integer
-index to where the substring was found (the Nth character from the start of the
+index to the substring's location (the Nth character from the start of the
string). Combining characters are counted separately. Variable-width encodings
-will lookahead to capture full character values. Returns -1 if the substring is
-not found.
+will lookahead to capture full character values. Returns -1 unless the
+substring is found.
=head3 Parrot_string_copy (was string_copy)
@@ -519,7 +518,7 @@
=head3 Parrot_string_grapheme_replace
Replaces a substring within the first string argument with the second string
-argument. An integer offset and length, in graphemes, specify where the removed
+argument. An integer offset and length in graphemes specify where the removed
substring starts and how long it is.
=head3 Parrot_string_chopn (was string_chopn)
@@ -550,14 +549,14 @@
=head3 string_system_end (was string_deinit)
-Terminate Parrot's string subsystem (clean up), including string allocation and
-garbage collection.
+Terminate and clean up Parrot's string subsystem, including string allocation
+and garbage collection.
=head3 string_max_bytes
-Calculate the number of bytes needed to contain a given number of characters in
-a particular encoding. It multiplies the maximum possible width of a character
-in the encoding by the number of characters requested.
+Calculate the number of bytes needed to hold a given number of characters in a
+particular encoding, multiplying the maximum possible width of a character in
+the encoding by the number of characters requested.
{{NOTE: pretty primitive and not very useful. May be deprecated.}}
@@ -575,8 +574,8 @@
=head3 string_make
-This was a crippled version of a string initializer, now replaced with the full
-version C<Parrot_string_new_init>.
+A crippled version of a string initializer, now replaced with the full version
+C<Parrot_string_new_init>.
=head3 string_capacity
@@ -657,8 +656,8 @@
=item set_number_native
-Set the string to a floating-point value, transforming the number to its string
-equivalent.
+Set the string to a floating-point value by transforming the number to its
+string equivalent.
=item set_string_native
@@ -671,13 +670,13 @@
=item set_string_same
-Set the String PMC's stored string value to be the same as another String PMC's
+Set the String PMC's stored string value to the same as another String PMC's
stored string value. {{NOTE: uses direct access into the storage of the two
PMCs, very ugly.}}
=item set_pmc
-Set the String PMC's stored string value to be the same as another PMC's string
+Set the String PMC's stored string value to the same as another PMC's string
value, as returned by that PMC's C<get_string> vtable function.
=item *bitwise*
@@ -697,8 +696,8 @@
=item is_equal_string
Compares the string values of two PMCs and returns true if they match exactly.
-{{NOTE: the documentation for the PMC says that it returns FALSE if they match.
-This is not the desired behavior.}}
+{{ NOTE: the documentation for the PMC says that it returns FALSE if they
+match. This is not the desired behavior. }}
=item is_same
@@ -783,14 +782,14 @@
=item reverse
-Reverse a string, one grapheme at a time. {{NOTE: Currenly only works for ASCII
-strings, because it reverses one C<char> at a time.}}
+Reverse a string, one grapheme at a time. {{ NOTE: Currenly only works for
+ASCII strings, because it reverses one C<char> at a time. }}
=item is_integer
-Checks if the string is just an integer. {{NOTE: Currently only works for ASCII
-strings, fix or deprecate.}}
+Checks if the string is just an integer. {{ NOTE: Currently only works for
+ASCII strings, fix or deprecate. }}
=back
