[PATCH] .dev files.

I'm happy to see new documentation, including the .dev files, appearing
in parrot.  However, I do have a small concern that we not set ourselves
in a position of maintaining multiple copies of the same information.

To be specific, I looked at byteorder.dev and noted a listing of all the
functions.  That's fine, but if the list of functions changes in the .c
file, someone has to remember to go back and update the list in
byteorder.dev as well. (I don't mean to pick on byteorder at all -- in
fact quite the contrary -- because it's small, well-commented, and
easy-to-follow, it's an easy practice ground for documentation!)

I tend to think that a better plan is to not bother listing the functions
(unless it makes the implementation discussion easier to understand) and
to rely on being able to pull them out of the relevant source file with
some sort of tool.  Further, keeping them right next to the appropriate
source in the .c file makes it more likely that they will be maintained in
sync.

To be specific, I propose three patches to illustrate how I think these
different files ought to work together.

1.  docs/pdds/pdd07_codingstd.pod:  I clarify where the list of functions
goes.

2.  byteorder.dev:  I took the existing one, put it in POD format, added a
few more implementation notes, and removed all the specific functions.

3.  byteorder.c: I put in POD documentation for all the functions. The
exact format is still to be determined, but I used perl5's utf8.c as an
example/model.  I chose the arbitrary apiname of 'byteorder'. That's
almost certainly wrong but is good enough to get started.

I'd welcome discussion on whether this looks like a reasonable way to
think about these .dev files, before we get too far along.

    Andy Dougherty		doughera@lafayette.edu


--- parrot-cvs/docs/pdds/pdd07_codingstd.pod	Wed Jul 17 11:35:19 2002
+++ parrot-andy/docs/pdds/pdd07_codingstd.pod	Wed Jul 17 12:14:55 2002
@@ -538,12 +538,17 @@
 this is in contrast to PDDs, which describe design decisions). This is
 the place for mini-essays on how to avoid overflows in unsigned
 arithmetic, or on the pros and cons of differing hash algorithms, and
-why the current one was chosen, and how it works. 
+why the current one was chosen, and how it works.
 
 In principle, someone coming to a particular source file for the first
 time should be able to read the F<.dev> file and gain an immediate
 overview of what the source file is for, the algorithms it implements,
 etc.
+
+The F<.dev> file is not usually the place for a complete listing of all
+functions in the source file.  That information is (presumably) already
+in the file itself, and duplicating it would only lead to more
+maintenance work.
 
 Currently no particular format or structure is imposed on the developer
 file, but it should have as a minimum the following sections:
--- parrot-cvs/byteorder.dev	Tue Jul 16 23:31:03 2002
+++ parrot-andy/byteorder.dev	Wed Jul 17 13:18:16 2002
@@ -1,57 +1,47 @@
-Overview
-The byteorder code will check the endianness of an INTVAL or
-an opcode_t value and swap from little to big, or big to little
-when appropriate.  Functions also exist to convert a 4, 8, 12,
-or 16 byte character buffer to big or little endian.
-The functions will be placed in the PackFile
-vtable and will be called when necessary.  It is hoped that
-the Parrot interpreter will not call these functions when
+=head1 Name
+
+    byteorder.c
+
+=head1 Overview
+
+The byteorder code will check the endianness of an INTVAL or an
+opcode_t value and swap from little to big, or big to little when
+appropriate.  Functions also exist to convert a 4, 8, 12, or 16 byte
+character buffer to big or little endian.  The functions will be placed
+in the PackFile vtable and will be called when necessary.  It is hoped
+that the Parrot interpreter will not call these functions when
 converting from and to the same byteorder.
 
-Data Structures and Algorithms
-The algorithm to change from one endian to another is
-identical and simplistic to understand.  Basically,
-the size of an INTVAL or opcode_t is used to
-determine at compile time how many bits should
-be shifted around.  Then, the correct bits are shifted
-the correct amounts (please look at source code for
-exact amounts).  The buffer change functions are implemented
-by a straight forward algorithm that assigns swaps all
-of the bytes.
-
-Important Functions
-fetch_iv_le - This function will convert an INTVAL into
-little endian format.  It is a noop if the native
-format is already little endian.
-fetch_iv_be - This function will convert an INTVAL into
-big endian format. It is a noop if the native
-format is already big endian.
-fetch_op_be - This function will convert an opcode_t into
-big endian format. It is a noop if the native
-format is already big endian.
-fetch_op_le - This function will convert an opcode_t into
-little endian fommat. It is a noop if the native
-format is already little endian.
-fetch_buf_le_(4,8,12,16) - This set of functions
-will convert an unsigned character buffer into
-little endian format.  Only a memcpy is performed
-if the native format is already little endian.
-fetch_buf_be_(4,8,12,16) - This set of functions
-will convert an unsigned character buffer into
-big endian format.  Only a memcpy is performed
-if the native format is already big endian.
+=head1 Data Structures and Algorithms
+
+The algorithms to change from one endian to another are identical and
+easy to understand.  Basically, the size of an INTVAL or opcode_t
+is used to determine at compile time how many bits should be shifted
+around.  Then, the correct bits are shifted the correct amounts (please
+look at source code for exact amounts).  The buffer change functions
+are implemented by a straightforward algorithm that assigns swaps all
+of the bytes.  All loops are unrolled for simplicity.
+
+On some systems, the htonl() family of functions may exist and be
+implemented in assembly.  (This is the case with glibc2-based Linux
+systems, if Parrot is compiled with -O or better).  It may be
+appropriate, at some point, to have Configure probe for such functions
+and use them where appropriate.
+
+=head1 Unimplemented Functions
 
-Unimplemented Functions
 endianize_fetch_int - fetch an INTVAL directly from a bytestream
 endianize_put_int - put an INTVAL directly on a bytestream
 
-History
+=head1 History
+
 Initial version by Melvin on 2002/05/01
 
-Notes
+=head1 Notes
+
 This assumes big or little endianness...other, more
 esoteric forms (such as middle endian) are not supported.
 Also, an assumption of 4 or 8 byte INTVAL's
 and opcode_t's is made.
 
-References
+=head1 References
--- parrot-cvs/byteorder.c	Wed Jul 17 11:35:16 2002
+++ parrot-andy/byteorder.c	Wed Jul 17 13:12:53 2002
@@ -14,6 +14,7 @@
  *     Initial version by Melvin on 2002/05/1
  *  Notes:
  *  References:
+ *     See byteorder.dev.
  */
 
 #include "parrot/parrot.h"
@@ -27,9 +28,14 @@
  */
 
 /* fetch_iv_le
- *   This function converts a 4 or 8 byte INTVAL into little
- *   endian format.  If the native format is already little
- *   endian, then no conversion is done.
+
+=for api byteorder INTVAL|fetch_iv_le|INTVAL w
+
+    This function converts a 4 or 8 byte INTVAL into little endian
+    format.  If the native format is already little endian, then no
+    conversion is done.
+
+=cut
  */
 INTVAL
 fetch_iv_le(INTVAL w)
@@ -54,9 +60,14 @@
 }
 
 /* fetch_iv_be
- *   This function converts a 4 or 8 byte INTVAL into big
- *   endian format.  If the native format is already big
- *   endian, then no conversion is done.
+
+=for api byteorder INTVAL|fetch_iv_be|INTVAL w
+
+    This function converts a 4 or 8 byte INTVAL into big endian
+    format.  If the native format is already big endian, then no
+    conversion is done.
+
+=cut
  */
 INTVAL
 fetch_iv_be(INTVAL w)
@@ -82,7 +93,13 @@
 
 
 /*
- * Same as above for opcode_t
+=for api byteorder opcode_t|fetch_op_be|opcode_t w
+
+    This function converts a 4 or 8 byte opcode_t into big endian
+    format.  If the native format is already big endian, then no
+    conversion is done.
+
+=cut
  */
 opcode_t
 fetch_op_be(opcode_t w)
@@ -107,6 +124,15 @@
 #endif
 }
 
+/*
+=for api byteorder opcode_t|fetch_op_le|opcode_t w
+
+    This function converts a 4 or 8 byte opcode_t into little endian
+    format.  If the native format is already little endian, then no
+    conversion is done.
+
+=cut
+*/
 opcode_t
 fetch_op_le(opcode_t w)
 {
@@ -131,9 +157,57 @@
 }
 
 /*
- * Unrolled routines for swapping various sizes from 32-128 bits
- * These should only be used if alignment is unknown or we are
- * pulling something out of a padded buffer.    
+=for api byteorder void|fetch_buf_be_4|unsigned char *rb|unsigned char *b
+
+    Fetches 4 bytes from b and copies them to rb in big-endian order.
+
+    These functions provide a set of routines for copying (and swapping
+    bytes, if appropriate) objects 4, 8, 12, or 16 bytes long.  Source
+    bytes are in b; the destination is rb.  These functions do not do
+    in-place swaps.  The source and destination must be different.
+
+    If no byte-swapping needs to be done, a simple memcpy() is
+    performed.
+
+    These functions should only be used if alignment is unknown or we
+    are pulling something out of a padded buffer.
+
+=for api byteorder void|fetch_buf_le_4|unsigned char *rb|unsigned char *b
+
+    Fetches 4 bytes from b and copies them to rb in little-endian order.
+    See fetch_buf_be_4.
+
+=for api byteorder void|fetch_buf_be_8|unsigned char *rb|unsigned char *b
+
+    Fetches 8 bytes from b and copies them to rb in big-endian order.
+    See fetch_buf_be_4.
+
+=for api byteorder void|fetch_buf_le_8|unsigned char *rb|unsigned char *b
+
+    Fetches 8 bytes from b and copies them to rb in little-endian order.
+    See fetch_buf_be_4.
+
+=for api byteorder void|fetch_buf_be_12|unsigned char *rb|unsigned char *b
+
+    Fetches 12 bytes from b and copies them to rb in big-endian order.
+    See fetch_buf_be_4.
+
+=for api byteorder void|fetch_buf_le_12|unsigned char *rb|unsigned char *b
+
+    Fetches 12 bytes from b and copies them to rb in little-endian order.
+    See fetch_buf_be_4.
+
+=for api byteorder void|fetch_buf_be_16|unsigned char *rb|unsigned char *b
+
+    Fetches 16 bytes from b and copies them to rb in big-endian order.
+    See fetch_buf_be_4.
+
+=for api byteorder void|fetch_buf_le_16|unsigned char *rb|unsigned char *b
+
+    Fetches 16 bytes from b and copies them to rb in little-endian order.
+    See fetch_buf_be_4.
+
+=cut
  */
 void
 fetch_buf_be_4(unsigned char *rb, unsigned char *b)


0
doughera
7/17/2002 5:35:31 PM
perl.perl6.internals 7376 articles. 0 followers. Follow

9 Replies
558 Views

Similar Articles

[PageSpeed] 20

Yes, after looking at this, I agree with Andy (and don't worry I don't think
you're picking on it,
I picked a small file so we could play with it until we found what we liked)
that it is a maintenence
headache to duplicate all of the functions.

However, I do think it is nice to be able to look at a .dev file and see the
functions that
are in the file and a short description of what they do.  That saves a
person digging through
the .c file to find what they are looking for.  Perhaps we could
automatically update
the .dev file with the POD found in the .c file?

Tanton
----- Original Message -----
From: "Andy Dougherty" <doughera@lafayette.edu>
To: "Perl6 Internals" <perl6-internals@perl.org>
Sent: Wednesday, July 17, 2002 1:35 PM
Subject: [PATCH] .dev files.


> I'm happy to see new documentation, including the .dev files, appearing
> in parrot.  However, I do have a small concern that we not set ourselves
> in a position of maintaining multiple copies of the same information.
>
> To be specific, I looked at byteorder.dev and noted a listing of all the
> functions.  That's fine, but if the list of functions changes in the .c
> file, someone has to remember to go back and update the list in
> byteorder.dev as well. (I don't mean to pick on byteorder at all -- in
> fact quite the contrary -- because it's small, well-commented, and
> easy-to-follow, it's an easy practice ground for documentation!)
>
> I tend to think that a better plan is to not bother listing the functions
> (unless it makes the implementation discussion easier to understand) and
> to rely on being able to pull them out of the relevant source file with
> some sort of tool.  Further, keeping them right next to the appropriate
> source in the .c file makes it more likely that they will be maintained in
> sync.
>
> To be specific, I propose three patches to illustrate how I think these
> different files ought to work together.
>
> 1.  docs/pdds/pdd07_codingstd.pod:  I clarify where the list of functions
> goes.
>
> 2.  byteorder.dev:  I took the existing one, put it in POD format, added a
> few more implementation notes, and removed all the specific functions.
>
> 3.  byteorder.c: I put in POD documentation for all the functions. The
> exact format is still to be determined, but I used perl5's utf8.c as an
> example/model.  I chose the arbitrary apiname of 'byteorder'. That's
> almost certainly wrong but is good enough to get started.
>
> I'd welcome discussion on whether this looks like a reasonable way to
> think about these .dev files, before we get too far along.
>
>     Andy Dougherty doughera@lafayette.edu
>
>
> --- parrot-cvs/docs/pdds/pdd07_codingstd.pod Wed Jul 17 11:35:19 2002
> +++ parrot-andy/docs/pdds/pdd07_codingstd.pod Wed Jul 17 12:14:55 2002
> @@ -538,12 +538,17 @@
>  this is in contrast to PDDs, which describe design decisions). This is
>  the place for mini-essays on how to avoid overflows in unsigned
>  arithmetic, or on the pros and cons of differing hash algorithms, and
> -why the current one was chosen, and how it works.
> +why the current one was chosen, and how it works.
>
>  In principle, someone coming to a particular source file for the first
>  time should be able to read the F<.dev> file and gain an immediate
>  overview of what the source file is for, the algorithms it implements,
>  etc.
> +
> +The F<.dev> file is not usually the place for a complete listing of all
> +functions in the source file.  That information is (presumably) already
> +in the file itself, and duplicating it would only lead to more
> +maintenance work.
>
>  Currently no particular format or structure is imposed on the developer
>  file, but it should have as a minimum the following sections:
> --- parrot-cvs/byteorder.dev Tue Jul 16 23:31:03 2002
> +++ parrot-andy/byteorder.dev Wed Jul 17 13:18:16 2002
> @@ -1,57 +1,47 @@
> -Overview
> -The byteorder code will check the endianness of an INTVAL or
> -an opcode_t value and swap from little to big, or big to little
> -when appropriate.  Functions also exist to convert a 4, 8, 12,
> -or 16 byte character buffer to big or little endian.
> -The functions will be placed in the PackFile
> -vtable and will be called when necessary.  It is hoped that
> -the Parrot interpreter will not call these functions when
> +=head1 Name
> +
> +    byteorder.c
> +
> +=head1 Overview
> +
> +The byteorder code will check the endianness of an INTVAL or an
> +opcode_t value and swap from little to big, or big to little when
> +appropriate.  Functions also exist to convert a 4, 8, 12, or 16 byte
> +character buffer to big or little endian.  The functions will be placed
> +in the PackFile vtable and will be called when necessary.  It is hoped
> +that the Parrot interpreter will not call these functions when
>  converting from and to the same byteorder.
>
> -Data Structures and Algorithms
> -The algorithm to change from one endian to another is
> -identical and simplistic to understand.  Basically,
> -the size of an INTVAL or opcode_t is used to
> -determine at compile time how many bits should
> -be shifted around.  Then, the correct bits are shifted
> -the correct amounts (please look at source code for
> -exact amounts).  The buffer change functions are implemented
> -by a straight forward algorithm that assigns swaps all
> -of the bytes.
> -
> -Important Functions
> -fetch_iv_le - This function will convert an INTVAL into
> -little endian format.  It is a noop if the native
> -format is already little endian.
> -fetch_iv_be - This function will convert an INTVAL into
> -big endian format. It is a noop if the native
> -format is already big endian.
> -fetch_op_be - This function will convert an opcode_t into
> -big endian format. It is a noop if the native
> -format is already big endian.
> -fetch_op_le - This function will convert an opcode_t into
> -little endian fommat. It is a noop if the native
> -format is already little endian.
> -fetch_buf_le_(4,8,12,16) - This set of functions
> -will convert an unsigned character buffer into
> -little endian format.  Only a memcpy is performed
> -if the native format is already little endian.
> -fetch_buf_be_(4,8,12,16) - This set of functions
> -will convert an unsigned character buffer into
> -big endian format.  Only a memcpy is performed
> -if the native format is already big endian.
> +=head1 Data Structures and Algorithms
> +
> +The algorithms to change from one endian to another are identical and
> +easy to understand.  Basically, the size of an INTVAL or opcode_t
> +is used to determine at compile time how many bits should be shifted
> +around.  Then, the correct bits are shifted the correct amounts (please
> +look at source code for exact amounts).  The buffer change functions
> +are implemented by a straightforward algorithm that assigns swaps all
> +of the bytes.  All loops are unrolled for simplicity.
> +
> +On some systems, the htonl() family of functions may exist and be
> +implemented in assembly.  (This is the case with glibc2-based Linux
> +systems, if Parrot is compiled with -O or better).  It may be
> +appropriate, at some point, to have Configure probe for such functions
> +and use them where appropriate.
> +
> +=head1 Unimplemented Functions
>
> -Unimplemented Functions
>  endianize_fetch_int - fetch an INTVAL directly from a bytestream
>  endianize_put_int - put an INTVAL directly on a bytestream
>
> -History
> +=head1 History
> +
>  Initial version by Melvin on 2002/05/01
>
> -Notes
> +=head1 Notes
> +
>  This assumes big or little endianness...other, more
>  esoteric forms (such as middle endian) are not supported.
>  Also, an assumption of 4 or 8 byte INTVAL's
>  and opcode_t's is made.
>
> -References
> +=head1 References
> --- parrot-cvs/byteorder.c Wed Jul 17 11:35:16 2002
> +++ parrot-andy/byteorder.c Wed Jul 17 13:12:53 2002
> @@ -14,6 +14,7 @@
>   *     Initial version by Melvin on 2002/05/1
>   *  Notes:
>   *  References:
> + *     See byteorder.dev.
>   */
>
>  #include "parrot/parrot.h"
> @@ -27,9 +28,14 @@
>   */
>
>  /* fetch_iv_le
> - *   This function converts a 4 or 8 byte INTVAL into little
> - *   endian format.  If the native format is already little
> - *   endian, then no conversion is done.
> +
> +=for api byteorder INTVAL|fetch_iv_le|INTVAL w
> +
> +    This function converts a 4 or 8 byte INTVAL into little endian
> +    format.  If the native format is already little endian, then no
> +    conversion is done.
> +
> +=cut
>   */
>  INTVAL
>  fetch_iv_le(INTVAL w)
> @@ -54,9 +60,14 @@
>  }
>
>  /* fetch_iv_be
> - *   This function converts a 4 or 8 byte INTVAL into big
> - *   endian format.  If the native format is already big
> - *   endian, then no conversion is done.
> +
> +=for api byteorder INTVAL|fetch_iv_be|INTVAL w
> +
> +    This function converts a 4 or 8 byte INTVAL into big endian
> +    format.  If the native format is already big endian, then no
> +    conversion is done.
> +
> +=cut
>   */
>  INTVAL
>  fetch_iv_be(INTVAL w)
> @@ -82,7 +93,13 @@
>
>
>  /*
> - * Same as above for opcode_t
> +=for api byteorder opcode_t|fetch_op_be|opcode_t w
> +
> +    This function converts a 4 or 8 byte opcode_t into big endian
> +    format.  If the native format is already big endian, then no
> +    conversion is done.
> +
> +=cut
>   */
>  opcode_t
>  fetch_op_be(opcode_t w)
> @@ -107,6 +124,15 @@
>  #endif
>  }
>
> +/*
> +=for api byteorder opcode_t|fetch_op_le|opcode_t w
> +
> +    This function converts a 4 or 8 byte opcode_t into little endian
> +    format.  If the native format is already little endian, then no
> +    conversion is done.
> +
> +=cut
> +*/
>  opcode_t
>  fetch_op_le(opcode_t w)
>  {
> @@ -131,9 +157,57 @@
>  }
>
>  /*
> - * Unrolled routines for swapping various sizes from 32-128 bits
> - * These should only be used if alignment is unknown or we are
> - * pulling something out of a padded buffer.
> +=for api byteorder void|fetch_buf_be_4|unsigned char *rb|unsigned char *b
> +
> +    Fetches 4 bytes from b and copies them to rb in big-endian order.
> +
> +    These functions provide a set of routines for copying (and swapping
> +    bytes, if appropriate) objects 4, 8, 12, or 16 bytes long.  Source
> +    bytes are in b; the destination is rb.  These functions do not do
> +    in-place swaps.  The source and destination must be different.
> +
> +    If no byte-swapping needs to be done, a simple memcpy() is
> +    performed.
> +
> +    These functions should only be used if alignment is unknown or we
> +    are pulling something out of a padded buffer.
> +
> +=for api byteorder void|fetch_buf_le_4|unsigned char *rb|unsigned char *b
> +
> +    Fetches 4 bytes from b and copies them to rb in little-endian order.
> +    See fetch_buf_be_4.
> +
> +=for api byteorder void|fetch_buf_be_8|unsigned char *rb|unsigned char *b
> +
> +    Fetches 8 bytes from b and copies them to rb in big-endian order.
> +    See fetch_buf_be_4.
> +
> +=for api byteorder void|fetch_buf_le_8|unsigned char *rb|unsigned char *b
> +
> +    Fetches 8 bytes from b and copies them to rb in little-endian order.
> +    See fetch_buf_be_4.
> +
> +=for api byteorder void|fetch_buf_be_12|unsigned char *rb|unsigned char
*b
> +
> +    Fetches 12 bytes from b and copies them to rb in big-endian order.
> +    See fetch_buf_be_4.
> +
> +=for api byteorder void|fetch_buf_le_12|unsigned char *rb|unsigned char
*b
> +
> +    Fetches 12 bytes from b and copies them to rb in little-endian order.
> +    See fetch_buf_be_4.
> +
> +=for api byteorder void|fetch_buf_be_16|unsigned char *rb|unsigned char
*b
> +
> +    Fetches 16 bytes from b and copies them to rb in big-endian order.
> +    See fetch_buf_be_4.
> +
> +=for api byteorder void|fetch_buf_le_16|unsigned char *rb|unsigned char
*b
> +
> +    Fetches 16 bytes from b and copies them to rb in little-endian order.
> +    See fetch_buf_be_4.
> +
> +=cut
>   */
>  void
>  fetch_buf_be_4(unsigned char *rb, unsigned char *b)
>
>
>
>

0
thgibbs
7/17/2002 5:42:08 PM
Tanton Gibbs wrote:
> . . . That saves a person digging through
> the .c file to find what they are looking for. 
> Perhaps we could automatically update the .dev
> file with the POD found in the .c file?

As someone else has already said, a better place
for the .dev information might be inside the .c
file itself.
I for one find the separation unnatural,
uncustomary, and de-sync-prone.
Frankly I just don't see what it buys us.

-- 
JohnDouglasPorter


__________________________________________________
Do You Yahoo!?
Yahoo! Autos - Get free new car price quotes
http://autos.yahoo.com
0
johndporter
7/17/2002 6:39:17 PM
That's a good point.  Perhaps the .dev file are superfluous.
If that is the case then all we need to do is change the .c file
header to contain the POD comments and then
intersperse POD in the code as Andy did.  Then
we can eliminate the .dev files and replace them with
a utility that will allow viewing of only the POD information.

Tanton
----- Original Message ----- 
From: "John Porter" <johndporter@yahoo.com>
To: "Perl6 Internals" <perl6-internals@perl.org>
Sent: Wednesday, July 17, 2002 2:39 PM
Subject: Re: [PATCH] .dev files.


> 
> Tanton Gibbs wrote:
> > . . . That saves a person digging through
> > the .c file to find what they are looking for. 
> > Perhaps we could automatically update the .dev
> > file with the POD found in the .c file?
> 
> As someone else has already said, a better place
> for the .dev information might be inside the .c
> file itself.
> I for one find the separation unnatural,
> uncustomary, and de-sync-prone.
> Frankly I just don't see what it buys us.
> 
> -- 
> JohnDouglasPorter
> 
> 
> __________________________________________________
> Do You Yahoo!?
> Yahoo! Autos - Get free new car price quotes
> http://autos.yahoo.com
> 
> 

0
thgibbs
7/17/2002 7:17:22 PM
John Porter:
# Tanton Gibbs wrote:
# > . . . That saves a person digging through
# > the .c file to find what they are looking for.
# > Perhaps we could automatically update the .dev
# > file with the POD found in the .c file?
# 
# As someone else has already said, a better place
# for the .dev information might be inside the .c
# file itself.
# I for one find the separation unnatural,
# uncustomary, and de-sync-prone.
# Frankly I just don't see what it buys us.

Do you really want to see a ten-page discussion of hashing algorithms
and why the current one was chosen in the middle of
classes/perlhash.pmc?  *That's* the sort of thing the .dev files are
for, not API documentation.  I agree that API docs should be in the
source file, but not much more than that.

--Brent Dax <brentdax@cpan.org>
@roles=map {"Parrot $_"} qw(embedding regexen Configure)

He who fights and runs away wasted valuable running time with the
fighting.

0
brentdax
7/17/2002 7:30:27 PM
Brent Dax wrote:
> Do you really want to see a ten-page discussion of hashing
> algorithms and why the current one was chosen in the middle
> of classes/perlhash.pmc?

I guess that wouldn't bother me as much as it might bother
some other people.


> *That's* the sort of thing the .dev files are for,
> not API documentation.

Well, fine; but then, that's not the sort of doco that needs
to have a 1-to-1 correspondence between source code file and
and doc file.

Furthermore -- why are .dev files not pdd files?
Is it because pdd is *design* while .dev is *implementation*?
If that's the case, then, like I said, having the source and
the doc in separate files, in different directories, makes
keeping them in sync more of a hassle and therefore more
likely to fall through the cracks.  Or "back-burnered".

I wonder what, if anything, XP has to say on this issue.

-- 
JohnDouglasPorter




__________________________________________________
Do You Yahoo!?
Yahoo! Autos - Get free new car price quotes
http://autos.yahoo.com
0
johndporter
7/17/2002 7:46:43 PM
On Wed, 17 Jul 2002, John Porter wrote:

> As someone else has already said, a better place
> for the .dev information might be inside the .c
> file itself.
> I for one find the separation unnatural,
> uncustomary, and de-sync-prone.
> Frankly I just don't see what it buys us.

Obviously, in principle, documentation could go anywhere, assuming it
actually gets written.

In practice, what we need is a supporting culture and infrastructure to
make it most likely that useful documentation will get written and be
in a place you can find it.

I think the purpose of the .dev files, as laid out in
docs/pdds/pdd07_codinstd.pod, is a reasonable one.  Here's an edited
excerpt:

    This text file contains documentation on all the implementation
    decisions associated with the source file.  This is the place for
    mini-essays on how to avoid overflows in unsigned arithmetic, or on
    the pros and cons of differing hash algorithms, and why the current
    one was chosen, and how it works.

    In principle, someone coming to a particular source file for the
    first time should be able to read the F<.dev> file and gain an
    immediate overview of what the source file is for, the algorithms
    it implements, etc.

Suppose, for example, that the author of hash.c chooses hashing
algorithm B over algorithm A.  At the top of hash.c, it would be a bit
odd to see a mini-essay describing A since it's never used.  On the
other hand, having done all the work to decide B is better than A for
parrot, it would be useful to record that decision somewhere.  hash.dev
is one sensible place for it.

Obviously, in practice, judgment will be needed for any particular bit
of documentation.  For example, take perl5's sv.c.  There are certainly
many implementation issues related to IV/UV/NV conversion that could be
discussed in some sort of mini-essay (and there is such a mini-essay in
sv.c).  On the other hand, I think many of the extensive comments on
those issues belong exactly where they are -- right next to the code in
question.

Obviously, in practice, judgment will be needed for any particular bit
of documentation.  If many of the .dev files end up very brief because
there were no significant implementation issues to address, or because
everything is clear from the .c file, or then so be it.  I suspect
there will be at least a few files that could benefit from some
mini-essay somewhere describing the implementation issues.

-- 
    Andy Dougherty		doughera@lafayette.edu
    Dept. of Physics
    Lafayette College, Easton PA 18042

0
doughera
7/17/2002 7:56:39 PM
Andy Dougherty wrote:
> I think the purpose of the .dev files, as laid out in
> docs/pdds/pdd07_codinstd.pod, is a reasonable one.
> Here's an edited excerpt: . . .

(Thanks, Andy.)

Well, given that definition of the purpose, I must 
persist in my opinion that the proper place for that
kind of doco is inside the source file.

Some people may think it "strange" to find a discussion
of implementation issues in a source code file, but
I don't.

Even so, since other people, whose opinions count for
something (as mine admittedly does not) think that
distancing the implementation from its justification
is a Good Thing, then... fine.  Whatever.

-- 
JohnDouglasPorter



__________________________________________________
Do You Yahoo!?
Yahoo! Autos - Get free new car price quotes
http://autos.yahoo.com
0
johndporter
7/17/2002 8:42:17 PM
very recently I wrote:
> ... fine.  Whatever.

People, if I'm coming across with a nasty or petulant tone,
I sincerely apologize.  It's really not what I was going for.

jdp


__________________________________________________
Do You Yahoo!?
Yahoo! Autos - Get free new car price quotes
http://autos.yahoo.com
0
johndporter
7/17/2002 9:20:40 PM
For what it's worth, I agree.  I think that when your documentation is 
tied to the structure of your source files, it only makes sense to put it 
IN the source files.

I don't think you can do literate programming half-way.  While I don't 
think literate programming is the right thing to do to produce 
well-organized design documentation (of the sort we're doing in the PDDs), 
it's a perfect way to do implementation documentation, of all sorts.

Moving .devs into our .c files would add a big block of POD at the 
beginning or the end.  So what?  Sounds good to me.

--Josh

At 11:39 on 07/17/2002 PDT, John Porter <johndporter@yahoo.com> wrote:

> 
> Tanton Gibbs wrote:
> > . . . That saves a person digging through
> > the .c file to find what they are looking for. 
> > Perhaps we could automatically update the .dev
> > file with the POD found in the .c file?
> 
> As someone else has already said, a better place
> for the .dev information might be inside the .c
> file itself.
> I for one find the separation unnatural,
> uncustomary, and de-sync-prone.
> Frankly I just don't see what it buys us.
> 
> -- 
> JohnDouglasPorter
> 
> 
> __________________________________________________
> Do You Yahoo!?
> Yahoo! Autos - Get free new car price quotes
> http://autos.yahoo.com


0
josh
7/18/2002 12:39:48 AM
Reply:

Similar Artilces:

[PATCH] File::Path::mkpath, /dev, /dev/dir and /dev/000000 changes
While fetching GD with CPAN.PM, I ran into some problems with File::Path::mkpath, in particular with rooted logicals: $ define/job/trans=conceal root_abcd_1 disk:[perl.cpan.build.id.blah.] mkpath('/root_abcd_1/lds') fails with a "invalid parameter" error when it tries to mkdir('/root_abcd_1'). There's a test in the code for a '000000' directory, but not for the lack of a directory....I suspect that the test was put in to prevent endless loops, prior to a modification of the File::Basename code. So here's a change that does the...

Patches, patches, patches...
To forestall potential incidents of Warnock's Dillemma... I'm about to apply a whole heap 'o patches to Parrot. (With appropriate [APPLIED] responses, I hope) If, at the end of the day, I have *not* applied or commented on a patch you've sent, it means I've Officially Missed It, so give another try. Sorry 'bout this. Too much mail in the mailbox, and going back in time is tricky, as it can miss subsequent discussions on patches 'n stuff. -- Dan --------------------------------------"it's like th...

[PATCH] no Carp #6 (File::Compare, File::Copy, File::Temp)
--Boundary-00=_FlpvCMb0sMUrG64 Content-Type: Text/Plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Content-Disposition: inline =2D----BEGIN PGP SIGNED MESSAGE----- Moin, attached patch loads Carp on demand for the aforementioned three modules. All tests successful. u=3D2.87 s=3D0.80 cu=3D186.18 cs=3D26.04 scripts=3D954 tests=3D107891 Although I think these patches are usefull, I'll stop until consens is=20 reached about whether they are usefull (I think so) or not. Makes no=20 sense to prepare them when they won't get applied....

[PATCH] Accept file exists error in ext/Win32API/File/t/file.t
------=_Part_120601_24109032.1182781395080 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Content-Disposition: inline Test 31 in ext/Win32API/File/t/file.t can also fail on ERROR_ALREADY_EXISTS (183): # Cannot create a file when that file already exists. not ok 31 The attached patch takes this into account. ------=_Part_120601_24109032.1182781395080 Content-Type: application/octet-stream; name=file_t.patch Content-Transfer-Encoding: base64 X-Attachment-Id: f_f3d1f7qg Content-Disposition: attachment; filename="file_t.patch&q...

[PATCH] Really ignore .patch files
--------------030708030005060005040501 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit G'day p5p, Having now created a few .patch files, it appears the current .gitignore in blead is reporting them as untracked, rather than simply ignoring them. The attached patch adjusts the .gitignore file to really ignore .patch files. Many thanks to Abigail for super-fast application of my other patches. Cheerio, Paul -- Paul Fenwick <pjf@perltraining.com.au> | http://perltraining.com.au/ Director of Training | Ph: +61 ...

[PATCH] for languages/perl6/perl6 --tree
Hello, by executing the command "perl6 --tree" there is to seen the following error message: [gz016@lgerd perl6]$ perl ./perl6 --tree -e 'print "alf"'; Can't call method "tree" on an undefined value at ./perl6 line 418. [gz016@lgerd perl6]$ The problem is that the function $parser->prog only returns a value if the function P6C::IMCC::init() is called first. So I fixed the program languages/perl6/perl6 that the modul P6C::IMCC is loaded and also the function P6C::IMCC::init is called generally. There is no need not to ...

[PATCH] Cleanup File::Temp test file
------=_Part_34733_22058077.1199467983477 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline The test file lib/File/Temp/t/fork.t improperly tries to use an automatic cleanup option with tempfile() (which does not support such an option). The temp file must be "manually" unlinked. Attached patch corrects this. ------=_Part_34733_22058077.1199467983477 Content-Type: application/octet-stream; name=file_temp.patch Content-Transfer-Encoding: base64 X-Attachment-Id: f_fb109g0r0 Content-Disposition: attachment; filenam...

[PATCH] Mention File::Spec in File::Basename
--GvXjxJ+pjyke8COw Content-Type: text/plain; charset=us-ascii Content-Disposition: inline My last patch to File::Basename, I swear. This one mentions File::Spec as an alternative as well as adding a SEE ALSO section. -- Michael G Schwern schwern@pobox.com http://www.pobox.com/~schwern Just call me 'Moron Sugar'. http://www.somethingpositive.net/sp05182002.shtml --GvXjxJ+pjyke8COw Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="fb.patch" --- lib/File/Basename.pm 2005/07/06 20:02:37 1.4 +++ lib/File/Basen...

[PATCH] very cosmetic patch for PerlIO test file
given crlf+PerlIO recent discussion, I dare suggesting very cosmetic change to my few lines of code - comment in a test file is a tiny bit incorrect --- crlf.t.orig Sat Jun 26 02:17:46 2004 +++ crlf.t Tue Sep 27 16:49:40 2005 @@ -40,7 +40,7 @@ open my $fh, "<:crlf", \$fcontents; local $/ = "xxx"; local $_ = <$fh>; - my $pos = tell $fh; # pos must be behind "xxx", before "\nyyy\n" + my $pos = tell $fh; # pos must be behind "xxx", before "\nxxy\n" seek $fh, $pos, 0; $/ = "\n"; $s...

PATCH: correct a few file references in README files
--000e0cd48494489d7b04659f1327 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit A few simple file reference fixes, like fixing the case on a reference to README.mint. Thanks, Mike --000e0cd48494489d7b04659f1327 Content-Type: application/octet-stream; name="0001-Correct-a-few-file-references-in-README-files.patch" Content-Disposition: attachment; filename="0001-Correct-a-few-file-references-in-README-files.patch" Content-Transfer-Encoding: base64 X-Attachment-Id: f_fsk75t6u0 RnJvbSA2ZjlhZTViZDA1NTdlMTUwOGFhYTE5MzMzZDAzM...

[PATCH File::Spec::*] a bunch of untested patches
I patched the other File::Spec::* modules to be consistent with the latest modification on File::Spec::Unix. There's no patch for File::Spec::Mac because it doesn't fall back to a non-tainted default location : it uses $ENV{TMPDIR} or cwd. Beware. I didn't test those patches : I only have access to various Unix machines. --- lib/File/Spec/VMS.pm.orig Wed Oct 10 18:57:43 2001 +++ lib/File/Spec/VMS.pm Tue Nov 6 21:29:14 2001 @@ -269,12 +269,23 @@ sys$scratch: $ENV{TMPDIR} +Since perl 5.8.0, if running under taint mode, and if $ENV{TMPDIR} +is tainted...

superreview requested: [Bug 266327] [BEOS] Saving internal files with nsLocalFileUnix::CreateUnique fails because of missing check for NS_EXCL in bfile.c : [Attachment 165205] The patch
Niels Reedijk <Niels.Reedijk@gmail.com> has asked tqh <thesuckiestemail@yahoo.se> for superreview: Bug 266327: [BEOS] Saving internal files with nsLocalFileUnix::CreateUnique fails because of missing check for NS_EXCL in bfile.c https://bugzilla.mozilla.org/show_bug.cgi?id=266327 Attachment 165205: The patch https://bugzilla.mozilla.org/attachment.cgi?id=165205&action=edit ...

superreview granted: [Bug 266327] [BEOS] Saving internal files with nsLocalFileUnix::CreateUnique fails because of missing check for NS_EXCL in bfile.c : [Attachment 165205] The patch
Wan-Teh Chang <wchang0222@aol.com> has granted Niels Reedijk <Niels.Reedijk@gmail.com>'s request for superreview: Bug 266327: [BEOS] Saving internal files with nsLocalFileUnix::CreateUnique fails because of missing check for NS_EXCL in bfile.c https://bugzilla.mozilla.org/show_bug.cgi?id=266327 Attachment 165205: The patch https://bugzilla.mozilla.org/attachment.cgi?id=165205&action=edit ...

superreview requested: [Bug 266327] [BEOS] Saving internal files with nsLocalFileUnix::CreateUnique fails because of missing check for NS_EXCL in bfile.c : [Attachment 165205] The patch #2
Niels Reedijk <Niels.Reedijk@gmail.com> has asked Wan-Teh Chang <wchang0222@aol.com> for superreview: Bug 266327: [BEOS] Saving internal files with nsLocalFileUnix::CreateUnique fails because of missing check for NS_EXCL in bfile.c https://bugzilla.mozilla.org/show_bug.cgi?id=266327 Attachment 165205: The patch https://bugzilla.mozilla.org/attachment.cgi?id=165205&action=edit ------- Additional Comments from Niels Reedijk <Niels.Reedijk@gmail.com> Asking super-review from the NSPR module owner. This is a BeOS only-change and will not affect other platforms in...

Web resources about - [PATCH] .dev files. - perl.perl6.internals

File:Shuttle Patch.svg - Wikipedia, the free encyclopedia
This image shows a flag , a coat of arms , a seal or some other official insignia . The use of such symbols is restricted in many countries. ...

Bradenton, FL Patch - News, Sports, Events, Businesses & Deals
Comprehensive and trusted local coverage of Bradenton, FL. Featuring news and events, business listings, discussions, announcements, photos and ...

Manassas, VA Patch - News, Sports, Events, Businesses & Deals
... your tip here and it will be sent straight to Jamie M. Rogers, James Cullum, Raytevia Evans, Greg Hambrick, and Todd Richissin,Manassas Patch's ...

Peachtree Corners, GA Patch - News, Sports, Events, Businesses & Deals
Comprehensive and trusted local coverage of Peachtree Corners and Berkeley Lake, GA. Featuring news and events, business listings, discussions, ...

Under the Hood: Dalvik patch for Facebook for Android - Facebook
Facebook Engineering hat eine Notiz mit dem Titel Under the Hood: Dalvik patch for Facebook for Android geschrieben. Du kannst den vollständigen ...

ISG: Playdom Buys Green Patch and Trippert Labs — On the Way to IPO?
... ones on Facebook, has confirmed a couple purchases we’ve been hearing rumors about recently. It has bought Facebook game developer Green Patch, ...

Salem NH Patch (@SalemNHPatch) on Twitter
Sign in Sign up You are on Twitter Mobile because you are using an old version of Internet Explorer. Learn more here Salem NH Patch @ SalemNHPatch ...

Dell Issues Patch For Content Adaptive Brightness Control On The XPS 13
... anytime you add something like this, you need to have a way to disable it for customers who don’t want it. Luckily Dell is now offering a patch ...

December Patch Tuesday avalanche of patches includes leaked Xbox certificate
(credit: CyberHades ) Today, Microsoft issued three new security advisories and a dozen new patches in the company’s monthly round of security ...

Windows 10 patch messing with your Office 2016 templates? Here's how you can get them back
A cumulative Windows 10 patch has had some Word 2016 users cringing in despair. The patch, titled Cumulative Update KB3124200 , is causing the ...

Resources last updated: 12/24/2015 11:47:04 PM