[svn:parrot] r47567 - in branches/cfunctionsdocs: config/gen/platform/ansi config/gen/platform/generic src/io src/string/charset t/codingstd

jkeenan at svn.parrot.org jkeenan at svn.parrot.org
Sat Jun 12 16:48:05 UTC 2010


Author: jkeenan
Date: Sat Jun 12 16:48:04 2010
New Revision: 47567
URL: https://trac.parrot.org/parrot/changeset/47567

Log:
[codingstd] Provide documentation for C functions.

Modified:
   branches/cfunctionsdocs/config/gen/platform/ansi/exec.c
   branches/cfunctionsdocs/config/gen/platform/ansi/time.c
   branches/cfunctionsdocs/config/gen/platform/generic/stat.c
   branches/cfunctionsdocs/src/io/api.c
   branches/cfunctionsdocs/src/string/charset/ascii.c
   branches/cfunctionsdocs/src/string/charset/binary.c
   branches/cfunctionsdocs/src/string/charset/iso-8859-1.c
   branches/cfunctionsdocs/src/string/charset/unicode.c
   branches/cfunctionsdocs/t/codingstd/c_function_docs.t

Modified: branches/cfunctionsdocs/config/gen/platform/ansi/exec.c
==============================================================================
--- branches/cfunctionsdocs/config/gen/platform/ansi/exec.c	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/config/gen/platform/ansi/exec.c	Sat Jun 12 16:48:04 2010	(r47567)
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2004-2008, Parrot Foundation.
+ * Copyright (C) 2004-2010, Parrot Foundation.
  */
 
 /*
@@ -25,7 +25,7 @@
 
 =item C<INTVAL Parrot_Run_OS_Command(PARROT_INTERP, STRING *command)>
 
-Spawn a subprocess
+B<Not yet implemented on this platform.> Spawn a subprocess.
 
 =cut
 
@@ -43,6 +43,8 @@
 
 =item C<INTVAL Parrot_Run_OS_Command_Argv(PARROT_INTERP, PMC *cmdargs)>
 
+B<Not yet implemented on this platform.>
+
 =cut
 
 */

Modified: branches/cfunctionsdocs/config/gen/platform/ansi/time.c
==============================================================================
--- branches/cfunctionsdocs/config/gen/platform/ansi/time.c	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/config/gen/platform/ansi/time.c	Sat Jun 12 16:48:04 2010	(r47567)
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2007, Parrot Foundation.
+ * Copyright (C) 2007-2010, Parrot Foundation.
  */
 
 /*
@@ -27,6 +27,8 @@
 
 =item C<INTVAL Parrot_intval_time(void)>
 
+Parrot wrapper around standard library C<time()> function, returning an INTVAL.
+
 =cut
 
 */
@@ -42,6 +44,9 @@
 
 =item C<FLOATVAL Parrot_floatval_time(void)>
 
+Note:  We are unable to provide this level of precision under ANSI-C, so we 
+just fall back to intval time for this.
+
 =cut
 
 */
@@ -49,8 +54,6 @@
 FLOATVAL
 Parrot_floatval_time(void)
 {
-    /* unable to provide this level of precision under ANSI-C, so just fall
-       back to intval time for this. */
     Parrot_warn(NULL, PARROT_WARNINGS_PLATFORM_FLAG, "Parrot_floatval_time not accurate");
     return (FLOATVAL)Parrot_intval_time();
 }

Modified: branches/cfunctionsdocs/config/gen/platform/generic/stat.c
==============================================================================
--- branches/cfunctionsdocs/config/gen/platform/generic/stat.c	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/config/gen/platform/generic/stat.c	Sat Jun 12 16:48:04 2010	(r47567)
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2007-2008, Parrot Foundation.
+ * Copyright (C) 2007-2010, Parrot Foundation.
  */
 
 /*
@@ -26,6 +26,8 @@
 
 =item C<PMC * Parrot_stat_file(PARROT_INTERP, STRING *filename)>
 
+B<Not implemented.>  Returns C<NULL>.
+
 =cut
 
 */
@@ -41,6 +43,8 @@
 =item C<PMC * Parrot_stat_info_pmc(PARROT_INTERP, STRING *filename, INTVAL
 thing)>
 
+B<Not implemented.>  Returns C<NULL>.
+
 =cut
 
 */
@@ -56,6 +60,55 @@
 =item C<static INTVAL stat_common(PARROT_INTERP, struct stat *statbuf, INTVAL
 thing, int status)>
 
+Stats the file, and returns the information specified by C<thing>. C<thing> can
+be one of:
+
+=over 4
+
+=item * C<STAT_EXISTS>
+
+=item * C<STAT_FILESIZE>
+
+=item * C<STAT_ISDIR>
+
+=item * C<STAT_ISREG>
+
+=item * C<STAT_ISDEV>
+
+=item * C<STAT_ACCESSTIME>
+
+=item * C<STAT_MODIFYTIME>
+
+=item * C<STAT_CHANGETIME>
+
+=item * C<STAT_UID>
+
+=item * C<STAT_GID>
+
+=item * C<STAT_PLATFORM_DEV>
+
+=item * C<STAT_PLATFORM_INODE>
+
+=item * C<STAT_PLATFORM_MODE>
+
+=item * C<STAT_PLATFORM_NLINKS>
+
+=item * C<STAT_PLATFORM_DEVTYPE>
+
+=item * C<STAT_PLATFORM_MODE>
+
+=item * C<STAT_PLATFORM_NLINKS>
+
+=item * C<STAT_PLATFORM_DEVTYPE>
+
+=item * C<STAT_PLATFORM_BLOCKSIZE>
+
+=item * C<STAT_PLATFORM_BLOCKS>
+
+=back
+
+C<STAT_CREATETIME> and C<STAT_BACKUPTIME> are not supported and will return C<-1>.
+
 =cut
 
 */
@@ -141,6 +194,8 @@
 =item C<INTVAL Parrot_stat_info_intval(PARROT_INTERP, STRING *file, INTVAL
 thing)>
 
+Returns the stat field given by C<thing> of file C<file>.
+
 =cut
 
 */
@@ -164,6 +219,8 @@
 =item C<INTVAL Parrot_fstat_info_intval(PARROT_INTERP, INTVAL file, INTVAL
 thing)>
 
+Returns the fstat field given by C<thing> from file identifier C<file>.
+
 =cut
 
 */
@@ -184,6 +241,8 @@
 =item C<FLOATVAL Parrot_stat_info_floatval(PARROT_INTERP, STRING *filename,
 INTVAL thing)>
 
+Currently returns C<-1.0> and has no side effects.
+
 =cut
 
 */
@@ -199,6 +258,8 @@
 =item C<STRING * Parrot_stat_info_string(PARROT_INTERP, STRING *filename, INTVAL
 thing)>
 
+B<Not implemented.> Returns C<NULL>.
+
 =cut
 
 */

Modified: branches/cfunctionsdocs/src/io/api.c
==============================================================================
--- branches/cfunctionsdocs/src/io/api.c	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/src/io/api.c	Sat Jun 12 16:48:04 2010	(r47567)
@@ -20,8 +20,8 @@
 is used in Parrot ops.
 
 TODO: Where possible, extract some of the filehandle-related details into
-src/io/filehandle.c, and extract the stringhandle details into
-src/io/io_string.c.
+F<src/io/filehandle.c>, and extract the stringhandle details into
+a new F<src/io/io_string.c>.
 
 =cut
 

Modified: branches/cfunctionsdocs/src/string/charset/ascii.c
==============================================================================
--- branches/cfunctionsdocs/src/string/charset/ascii.c	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/src/string/charset/ascii.c	Sat Jun 12 16:48:04 2010	(r47567)
@@ -678,6 +678,8 @@
 =item C<static INTVAL is_cclass(PARROT_INTERP, INTVAL flags, const STRING *src,
 UINTVAL offset)>
 
+Returns Boolean.
+
 =cut
 
 */
@@ -729,6 +731,8 @@
 =item C<static INTVAL find_not_cclass(PARROT_INTERP, INTVAL flags, const STRING
 *src, UINTVAL offset, UINTVAL count)>
 
+Returns C<INTVAL>.
+
 =cut
 
 */
@@ -883,6 +887,14 @@
 }
 
 /*
+
+=back
+
+=cut
+
+*/
+
+/*
  * Local variables:
  *   c-file-style: "parrot"
  * End:

Modified: branches/cfunctionsdocs/src/string/charset/binary.c
==============================================================================
--- branches/cfunctionsdocs/src/string/charset/binary.c	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/src/string/charset/binary.c	Sat Jun 12 16:48:04 2010	(r47567)
@@ -407,6 +407,8 @@
 =item C<static INTVAL is_cclass(PARROT_INTERP, INTVAL flags, const STRING *src,
 UINTVAL offset)>
 
+Returns Boolean.
+
 =cut
 
 */
@@ -423,6 +425,8 @@
 =item C<static INTVAL find_cclass(PARROT_INTERP, INTVAL flags, const STRING
 *src, UINTVAL offset, UINTVAL count)>
 
+Find a character in the given character class.
+
 =cut
 
 */
@@ -440,6 +444,8 @@
 =item C<static INTVAL find_not_cclass(PARROT_INTERP, INTVAL flags, const STRING
 *src, UINTVAL offset, UINTVAL count)>
 
+Returns C<INTVAL>.
+
 =cut
 
 */
@@ -456,6 +462,9 @@
 
 =item C<static STRING * string_from_codepoint(PARROT_INTERP, UINTVAL codepoint)>
 
+Creates a new STRING object from a single codepoint C<codepoint>. Returns
+the new STRING.
+
 =cut
 
 */

Modified: branches/cfunctionsdocs/src/string/charset/iso-8859-1.c
==============================================================================
--- branches/cfunctionsdocs/src/string/charset/iso-8859-1.c	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/src/string/charset/iso-8859-1.c	Sat Jun 12 16:48:04 2010	(r47567)
@@ -541,6 +541,8 @@
 =item C<static INTVAL is_cclass(PARROT_INTERP, INTVAL flags, const STRING *src,
 UINTVAL offset)>
 
+Returns Boolean.
+
 =cut
 
 */
@@ -591,6 +593,8 @@
 =item C<static INTVAL find_not_cclass(PARROT_INTERP, INTVAL flags, const STRING
 *src, UINTVAL offset, UINTVAL count)>
 
+Returns C<INTVAL>.
+
 =cut
 
 */

Modified: branches/cfunctionsdocs/src/string/charset/unicode.c
==============================================================================
--- branches/cfunctionsdocs/src/string/charset/unicode.c	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/src/string/charset/unicode.c	Sat Jun 12 16:48:04 2010	(r47567)
@@ -738,6 +738,8 @@
 
 =item C<static int u_iscclass(PARROT_INTERP, UINTVAL codepoint, INTVAL flags)>
 
+Returns Boolean.
+
 =cut
 
 */
@@ -834,6 +836,8 @@
 =item C<static INTVAL is_cclass(PARROT_INTERP, INTVAL flags, const STRING *src,
 UINTVAL offset)>
 
+Returns Boolean.
+
 =cut
 
 */
@@ -861,6 +865,8 @@
 =item C<static INTVAL find_cclass(PARROT_INTERP, INTVAL flags, const STRING
 *src, UINTVAL offset, UINTVAL count)>
 
+Find a character in the given character class.
+
 =cut
 
 */
@@ -901,6 +907,8 @@
 =item C<static INTVAL find_not_cclass(PARROT_INTERP, INTVAL flags, const STRING
 *src, UINTVAL offset, UINTVAL count)>
 
+Returns C<INTVAL>.
+
 =cut
 
 */

Modified: branches/cfunctionsdocs/t/codingstd/c_function_docs.t
==============================================================================
--- branches/cfunctionsdocs/t/codingstd/c_function_docs.t	Sat Jun 12 16:22:22 2010	(r47566)
+++ branches/cfunctionsdocs/t/codingstd/c_function_docs.t	Sat Jun 12 16:48:04 2010	(r47567)
@@ -92,18 +92,9 @@
 
 __DATA__
 compilers/pirc/src/pircapi.c
-config/gen/platform/ansi/exec.c
-config/gen/platform/ansi/time.c
 config/gen/platform/darwin/memalign.c
 config/gen/platform/generic/memalign.c
-config/gen/platform/generic/stat.c
 examples/compilers/japhc.c
-src/gc/generational_ms.c
-src/io/io_string.c
-src/string/charset/ascii.c
-src/string/charset/binary.c
-src/string/charset/iso-8859-1.c
-src/string/charset/unicode.c
 
 # Local Variables:
 #   mode: cperl


More information about the parrot-commits mailing list