You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucy.apache.org by nw...@apache.org on 2016/02/06 15:17:41 UTC
[08/14] lucy-clownfish git commit: Improve docucomments
Improve docucomments
Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/6210eac9
Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/6210eac9
Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/6210eac9
Branch: refs/heads/master
Commit: 6210eac9aa289b0068139eacd50c0e2301897871
Parents: a7f797c
Author: Nick Wellnhofer <we...@aevum.de>
Authored: Wed Feb 3 15:03:02 2016 +0100
Committer: Nick Wellnhofer <we...@aevum.de>
Committed: Wed Feb 3 15:50:07 2016 +0100
----------------------------------------------------------------------
runtime/core/Clownfish/Blob.cfh | 37 ++++++++-
runtime/core/Clownfish/Boolean.cfh | 2 +
runtime/core/Clownfish/ByteBuf.cfh | 54 ++++++++----
runtime/core/Clownfish/CharBuf.cfh | 37 +++++++--
runtime/core/Clownfish/Class.cfh | 11 ++-
runtime/core/Clownfish/Err.cfh | 10 +--
runtime/core/Clownfish/Hash.cfh | 35 ++++++--
runtime/core/Clownfish/HashIterator.cfh | 17 ++++
runtime/core/Clownfish/Num.cfh | 55 ++++++++++--
runtime/core/Clownfish/String.cfh | 120 ++++++++++++++++++++++-----
runtime/core/Clownfish/Util/Memory.cfh | 12 +--
runtime/core/Clownfish/Vector.cfh | 31 ++++---
12 files changed, 346 insertions(+), 75 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/Blob.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Blob.cfh b/runtime/core/Clownfish/Blob.cfh
index fce8379..0fa3028 100644
--- a/runtime/core/Clownfish/Blob.cfh
+++ b/runtime/core/Clownfish/Blob.cfh
@@ -26,28 +26,60 @@ public final class Clownfish::Blob inherits Clownfish::Obj {
size_t size;
bool owns_buf;
+ /** Return a new Blob which holds a copy of the passed-in bytes.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
+ */
public inert incremented Blob*
new(const void *bytes, size_t size);
+ /** Initialize a Blob which holds a copy of the passed-in bytes.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
+ */
public inert Blob*
init(Blob *self, const void *bytes, size_t size);
+ /** Return a new Blob which assumes ownership of the passed-in bytes.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
+ */
public inert incremented Blob*
new_steal(void *bytes, size_t size);
+ /** Initialize a Blob which assumes ownership of the passed-in bytes.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
+ */
public inert Blob*
init_steal(Blob *self, void *bytes, size_t size);
+ /** Return a new Blob which wraps an external buffer. The buffer must
+ * stay unchanged for the lifetime of the Blob.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
+ */
public inert incremented Blob*
new_wrap(const void *bytes, size_t size);
+ /** Initialize a Blob which wraps an external buffer. The buffer must
+ * stay unchanged for the lifetime of the Blob.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
+ */
public inert Blob*
init_wrap(Blob *self, const void *bytes, size_t size);
void*
To_Host(Blob *self);
- /** Accessor for "size" member.
+ /** Return the number of bytes held by the Blob.
*/
public size_t
Get_Size(Blob *self);
@@ -58,6 +90,9 @@ public final class Clownfish::Blob inherits Clownfish::Obj {
Get_Buf(Blob *self);
/** Test whether the Blob matches the passed-in bytes.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
*/
public bool
Equals_Bytes(Blob *self, const void *bytes, size_t size);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/Boolean.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Boolean.cfh b/runtime/core/Clownfish/Boolean.cfh
index 29b5f12..6d389db 100644
--- a/runtime/core/Clownfish/Boolean.cfh
+++ b/runtime/core/Clownfish/Boolean.cfh
@@ -44,6 +44,8 @@ public final class Clownfish::Boolean nickname Bool {
void*
To_Host(Boolean *self);
+ /** Return the value of the Boolean.
+ */
public bool
Get_Value(Boolean *self);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/ByteBuf.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/ByteBuf.cfh b/runtime/core/Clownfish/ByteBuf.cfh
index 8e25d6c..a86bbb2 100644
--- a/runtime/core/Clownfish/ByteBuf.cfh
+++ b/runtime/core/Clownfish/ByteBuf.cfh
@@ -24,33 +24,52 @@ public final class Clownfish::ByteBuf nickname BB inherits Clownfish::Obj {
char *buf;
size_t size; /* number of valid bytes */
- size_t cap; /* allocated bytes, including terminating null */
+ size_t cap; /* allocated bytes */
- /**
- * @param capacity initial capacity of the ByteBuf, in bytes.
+ /** Return a new zero-sized ByteBuf.
+ *
+ * @param capacity Initial minimum capacity of the ByteBuf, in bytes.
*/
public inert incremented ByteBuf*
new(size_t capacity = 0);
+ /** Initialize a ByteBuf.
+ *
+ * @param capacity Initial minimum capacity of the ByteBuf, in bytes.
+ */
public inert ByteBuf*
init(ByteBuf *self, size_t capacity = 0);
- /** Return a pointer to a new ByteBuf which holds a copy of the passed-in
- * bytes.
+ /** Return a new ByteBuf which holds a copy of the passed-in bytes.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
*/
public inert incremented ByteBuf*
new_bytes(const void *bytes, size_t size);
+ /** Initialize a ByteBuf which holds a copy of the passed-in bytes.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
+ */
public inert ByteBuf*
init_bytes(ByteBuf *self, const void *bytes, size_t size);
- /** Return a pointer to a new ByteBuf which assumes ownership of the
- * passed-in string.
+ /** Return a new ByteBuf which assumes ownership of the passed-in string.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Initial size of the ByteBuf in bytes.
+ * @param capacity Total allocated bytes in the array.
*/
public inert incremented ByteBuf*
new_steal_bytes(void *bytes, size_t size, size_t capacity);
- /** Initialize the ByteBuf and assume ownership of the passed-in string.
+ /** Initialize a ByteBuf and assume ownership of the passed-in string.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Initial size of the ByteBuf in bytes.
+ * @param capacity Total allocated bytes in the array.
*/
public inert ByteBuf*
init_steal_bytes(ByteBuf *self, void *bytes, size_t size,
@@ -59,13 +78,13 @@ public final class Clownfish::ByteBuf nickname BB inherits Clownfish::Obj {
void*
To_Host(ByteBuf *self);
- /** Set the object's size member. If greater than the object's capacity,
+ /** Resize the ByteBuf to `size`. If greater than the object's capacity,
* throws an error.
*/
public void
Set_Size(ByteBuf *self, size_t size);
- /** Accessor for "size" member.
+ /** Return the size of the ByteBuf in bytes.
*/
public size_t
Get_Size(ByteBuf *self);
@@ -75,32 +94,36 @@ public final class Clownfish::ByteBuf nickname BB inherits Clownfish::Obj {
public nullable char*
Get_Buf(ByteBuf *self);
- /** Return the number of bytes in the Object's allocation.
+ /** Return the number of bytes in the ByteBuf's allocation.
*/
public size_t
Get_Capacity(ByteBuf *self);
/** Concatenate the passed-in bytes onto the end of the ByteBuf. Allocate
* more memory as needed.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
*/
public void
Cat_Bytes(ByteBuf *self, const void *bytes, size_t size);
- /** Concatenate the contents of `other` onto the end of the
+ /** Concatenate the contents of [](Blob) `blob` onto the end of the
* original ByteBuf. Allocate more memory as needed.
*/
public void
Cat(ByteBuf *self, Blob *blob);
/** Assign more memory to the ByteBuf, if it doesn't already have enough
- * room to hold `size` bytes. Cannot shrink the allocation.
+ * room to hold `capacity` bytes. Cannot shrink the allocation.
*
+ * @param capacity The new minimum capacity of the ByteBuf.
* @return a pointer to the raw buffer.
*/
public nullable char*
Grow(ByteBuf *self, size_t capacity);
- /** Return the content of the ByteBuf as Blob and clear the ByteBuf.
+ /** Return the content of the ByteBuf as ()[Blob] and clear the ByteBuf.
*/
public incremented Blob*
Yield_Blob(ByteBuf *self);
@@ -118,6 +141,9 @@ public final class Clownfish::ByteBuf nickname BB inherits Clownfish::Obj {
Trusted_Utf8_To_String(ByteBuf *self);
/** Test whether the ByteBuf matches the passed-in bytes.
+ *
+ * @param bytes Pointer to an array of bytes.
+ * @param size Size of the array in bytes.
*/
public bool
Equals_Bytes(ByteBuf *self, const void *bytes, size_t size);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/CharBuf.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/CharBuf.cfh b/runtime/core/Clownfish/CharBuf.cfh
index 1b61879..1270a2d 100644
--- a/runtime/core/Clownfish/CharBuf.cfh
+++ b/runtime/core/Clownfish/CharBuf.cfh
@@ -25,27 +25,43 @@ public final class Clownfish::CharBuf nickname CB
char *ptr;
size_t size;
- size_t cap; /* allocated bytes, including terminating null */
+ size_t cap; /* allocated bytes */
+ /** Return a new CharBuf.
+ *
+ * @param capacity Initial minimum capacity of the CharBuf, in bytes.
+ */
public inert incremented CharBuf*
new(size_t capacity = 0);
+ /** Initialize a CharBuf.
+ *
+ * @param capacity Initial minimum capacity of the CharBuf, in bytes.
+ */
public inert CharBuf*
init(CharBuf *self, size_t capacity = 0);
/** Concatenate the passed-in string onto the end of the CharBuf.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public void
Cat_Utf8(CharBuf *self, const char *utf8, size_t size);
/** Concatenate the supplied text onto the end of the CharBuf. Don't
* check for UTF-8 validity.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public void
Cat_Trusted_Utf8(CharBuf *self, const char *utf8, size_t size);
- /** Concatenate the contents of `string` onto the end of the
+ /** Concatenate the contents of [](String) `string` onto the end of the
* caller.
+ *
+ * @param string The String to concatenate.
*/
public void
Cat(CharBuf *self, String *string);
@@ -59,19 +75,26 @@ public final class Clownfish::CharBuf nickname CB
* floats: %f64
* hex: %x32
*
- * Note that all Clownfish Objects, including CharBufs, are printed via
+ * Note that all Clownfish Objects, including Strings, are printed via
* %o (which invokes [](Obj.To_String)).
+ *
+ * @param pattern The format string.
+ * @param args A `va_list` containing the arguments.
*/
public void
VCatF(CharBuf *self, const char *pattern, va_list args);
- /** Invokes CB_VCatF to concatenate formatted arguments. Note that this
+ /** Invokes [](.VCatF) to concatenate formatted arguments. Note that this
* is only a function and not a method.
+ *
+ * @param pattern The format string.
*/
public inert void
catf(CharBuf *self, const char *pattern, ...);
/** Concatenate one Unicode character onto the end of the CharBuf.
+ *
+ * @param code_point The code point of the Unicode character.
*/
public void
Cat_Char(CharBuf *self, int32_t code_point);
@@ -79,6 +102,8 @@ public final class Clownfish::CharBuf nickname CB
/** Assign more memory to the CharBuf, if it doesn't already have enough
* room to hold a string of `size` bytes. Cannot shrink the
* allocation.
+ *
+ * @param capacity The new minimum capacity of the ByteBuf.
*/
public void
Grow(CharBuf *self, size_t capacity);
@@ -88,7 +113,7 @@ public final class Clownfish::CharBuf nickname CB
public void
Clear(CharBuf *self);
- /** Get the CharBuf's `size` attribute.
+ /** Return the size of the CharBuf's content in bytes.
*/
public size_t
Get_Size(CharBuf *self);
@@ -102,7 +127,7 @@ public final class Clownfish::CharBuf nickname CB
public incremented String*
To_String(CharBuf *self);
- /** Return the content of the CharBuf as String and clear the CharBuf.
+ /** Return the content of the CharBuf as [](String) and clear the CharBuf.
* This is more efficient than [](.To_String).
*/
public incremented String*
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/Class.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Class.cfh b/runtime/core/Clownfish/Class.cfh
index 7b43e1b..7b5bb59 100644
--- a/runtime/core/Clownfish/Class.cfh
+++ b/runtime/core/Clownfish/Class.cfh
@@ -45,9 +45,9 @@ public final class Clownfish::Class inherits Clownfish::Obj {
/** Return a singleton. If a Class can be found in the registry based on
* the supplied class name, it will be returned. Otherwise, a new Class
- * will be created using [parent] as a base.
+ * will be created using `parent` as a base.
*
- * If [parent] is NULL, an attempt will be made to find it. If the
+ * If `parent` is [](@null), an attempt will be made to find it. If the
* attempt fails, an error will result.
*/
public inert Class*
@@ -118,12 +118,19 @@ public final class Clownfish::Class inherits Clownfish::Obj {
void
Exclude_Host_Method(Class *self, const char *meth_name);
+ /** Return the name of the class.
+ */
public String*
Get_Name(Class *self);
+ /** Return the parent class, or [](@null) for a root of the class
+ * hierarchy.
+ */
public nullable Class*
Get_Parent(Class *self);
+ /** Return the number of bytes needed to hold an object the class.
+ */
public uint32_t
Get_Obj_Alloc_Size(Class *self);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/Err.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Err.cfh b/runtime/core/Clownfish/Err.cfh
index d863119..e6dce87 100644
--- a/runtime/core/Clownfish/Err.cfh
+++ b/runtime/core/Clownfish/Err.cfh
@@ -55,7 +55,7 @@ public class Clownfish::Err inherits Clownfish::Obj {
public incremented String*
To_String(Err *self);
- /** Concatenate the supplied argument onto the internal "mess".
+ /** Concatenate the supplied argument onto the error message.
*/
public void
Cat_Mess(Err *self, String *mess);
@@ -63,17 +63,17 @@ public class Clownfish::Err inherits Clownfish::Obj {
public String*
Get_Mess(Err *self);
- /** Add information about the current stack frame onto `mess`.
+ /** Add information about the current stack frame onto the error message.
*/
void
Add_Frame(Err *self, const char *file, int line, const char *func);
- /** Set the value of "error", a per-thread Err shared variable.
+ /** Set the global error object, a per-thread Err shared variable.
*/
public inert void
set_error(decremented Err *error);
- /** Retrieve per-thread Err shared variable "error".
+ /** Retrieve the global error object, a per-thread Err shared variable.
*/
public inert nullable Err*
get_error();
@@ -100,7 +100,7 @@ public class Clownfish::Err inherits Clownfish::Obj {
*/
inert void
throw_at(Class *klass, const char *file, int line, const char *func,
- const char *pattern, ...);
+ const char *pattern, ...);
/** Throw an existing exception after tacking on additional context data.
*/
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/Hash.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Hash.cfh b/runtime/core/Clownfish/Hash.cfh
index f653bfe..b2fa243 100644
--- a/runtime/core/Clownfish/Hash.cfh
+++ b/runtime/core/Clownfish/Hash.cfh
@@ -31,10 +31,16 @@ public final class Clownfish::Hash inherits Clownfish::Obj {
inert void
init_class();
+ /** Return a new Hash.
+ *
+ * @param capacity The number of elements that the hash will be asked to
+ * hold initially.
+ */
public inert incremented Hash*
new(size_t capacity = 0);
- /**
+ /** Initialize a Hash.
+ *
* @param capacity The number of elements that the hash will be asked to
* hold initially.
*/
@@ -57,6 +63,12 @@ public final class Clownfish::Hash inherits Clownfish::Obj {
public void
Store(Hash *self, String *key, decremented nullable Obj *value);
+ /** Store a key-value pair using a raw UTF-8 key.
+ *
+ * @param utf8 Pointer to UTF-8 character data of the key.
+ * @param size Size of UTF-8 character data in bytes.
+ * @param The Obj to store.
+ */
public void
Store_Utf8(Hash *self, const char *utf8, size_t size,
decremented nullable Obj *value);
@@ -68,6 +80,12 @@ public final class Clownfish::Hash inherits Clownfish::Obj {
public nullable Obj*
Fetch(Hash *self, String *key);
+ /** Fetch the value associated with a raw UTF-8 key.
+ *
+ * @param utf8 Pointer to UTF-8 character data of the key.
+ * @param size Size of UTF-8 character data in bytes.
+ * @return the value, or NULL if `key` is not present.
+ */
public nullable Obj*
Fetch_Utf8(Hash *self, const char *utf8, size_t size);
@@ -79,6 +97,13 @@ public final class Clownfish::Hash inherits Clownfish::Obj {
public incremented nullable Obj*
Delete(Hash *self, String *key);
+ /** Attempt to delete a key-value pair from the hash.
+ *
+ * @param utf8 Pointer to UTF-8 character data of the key.
+ * @param size Size of UTF-8 character data in bytes.
+ * @return the value if `key` exists and thus deletion
+ * succeeds; otherwise NULL.
+ */
public incremented nullable Obj*
Delete_Utf8(Hash *self, const char *utf8, size_t size);
@@ -87,12 +112,12 @@ public final class Clownfish::Hash inherits Clownfish::Obj {
public bool
Has_Key(Hash *self, String *key);
- /** Return an Vector of pointers to the hash's keys.
+ /** Return a Vector of pointers to the hash's keys.
*/
public incremented Vector*
Keys(Hash *self);
- /** Return an Vector of pointers to the hash's values.
+ /** Return a Vector of pointers to the hash's values.
*/
public incremented Vector*
Values(Hash *self);
@@ -100,9 +125,7 @@ public final class Clownfish::Hash inherits Clownfish::Obj {
size_t
Get_Capacity(Hash *self);
- /** Accessor for Hash's "size" member.
- *
- * @return the number of key-value pairs.
+ /** Return the number of key-value pairs.
*/
public size_t
Get_Size(Hash *self);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/HashIterator.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/HashIterator.cfh b/runtime/core/Clownfish/HashIterator.cfh
index 74ebc44..0815d3a 100644
--- a/runtime/core/Clownfish/HashIterator.cfh
+++ b/runtime/core/Clownfish/HashIterator.cfh
@@ -30,18 +30,35 @@ public final class Clownfish::HashIterator nickname HashIter
inert void
init_class();
+ /** Return a HashIterator for `hash`.
+ */
public inert incremented HashIterator*
new(Hash *hash);
+ /** Initialize a HashIterator for `hash`.
+ */
public inert HashIterator*
init(HashIterator *self, Hash *hash);
+ /** Advance the iterator to the next key-value pair.
+ *
+ * @return true if there's another key-value pair, false if the iterator
+ * is exhausted.
+ */
public bool
Next(HashIterator *self);
+ /** Return the key of the current key-value pair. It's not allowed to
+ * call this method before [](.Next) was called for the first time or
+ * after the iterator was exhausted.
+ */
public String*
Get_Key(HashIterator *self);
+ /** Return the value of the current key-value pair. It's not allowed to
+ * call this method before [](.Next) was called for the first time or
+ * after the iterator was exhausted.
+ */
public nullable Obj*
Get_Value(HashIterator *self);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/Num.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Num.cfh b/runtime/core/Clownfish/Num.cfh
index dad03a5..0f74f9d 100644
--- a/runtime/core/Clownfish/Num.cfh
+++ b/runtime/core/Clownfish/Num.cfh
@@ -22,30 +22,52 @@ public final class Clownfish::Float {
double value;
- /**
+ /** Return a new Float.
+ *
* @param value Initial value.
*/
public inert Float*
- init(Float* self, double value);
+ new(double value);
+ /** Initialize a Float.
+ *
+ * @param value Initial value.
+ */
public inert Float*
- new(double value);
+ init(Float* self, double value);
void*
To_Host(Float *self);
+ /** Return the value of the Float.
+ */
public double
Get_Value(Float *self);
+ /** Convert the Float to an integer, truncating toward zero. Throw an
+ * exception if the value is out of the range of an `int64_t`.
+ */
public int64_t
To_I64(Float *self);
public incremented String*
To_String(Float *self);
+ /** Indicate whether two numbers are the same.
+ *
+ * @param other A Float or an Integer.
+ */
public bool
Equals(Float *self, Obj *other);
+ /** Indicate whether one number is less than, equal to, or greater than
+ * another.
+ *
+ * @param other A Float or an Integer.
+ * @return 0 if the numbers are equal, a negative number if `self` is
+ * less than `other`, and a positive number if `self` is greater than
+ * `other`.
+ */
public int32_t
Compare_To(Float *self, Obj *other);
@@ -60,30 +82,51 @@ public final class Clownfish::Integer nickname Int {
int64_t value;
- /**
+ /** Return a new Integer.
+ *
* @param value Initial value.
*/
public inert Integer*
- init(Integer* self, int64_t value);
+ new(int64_t value);
+ /** Initialize an Integer.
+ *
+ * @param value Initial value.
+ */
public inert Integer*
- new(int64_t value);
+ init(Integer* self, int64_t value);
void*
To_Host(Integer *self);
+ /** Return the value of the Integer.
+ */
public int64_t
Get_Value(Integer *self);
+ /** Convert the Integer to floating point.
+ */
public double
To_F64(Integer *self);
public incremented String*
To_String(Integer *self);
+ /** Indicate whether two numbers are the same.
+ *
+ * @param other An Integer or a Float.
+ */
public bool
Equals(Integer *self, Obj *other);
+ /** Indicate whether one number is less than, equal to, or greater than
+ * another.
+ *
+ * @param other An Integer or a Float.
+ * @return 0 if the numbers are equal, a negative number if `self` is
+ * less than `other`, and a positive number if `self` is greater than
+ * `other`.
+ */
public int32_t
Compare_To(Integer *self, Obj *other);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/String.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/String.cfh b/runtime/core/Clownfish/String.cfh
index 3d13311..3d7ba5d 100644
--- a/runtime/core/Clownfish/String.cfh
+++ b/runtime/core/Clownfish/String.cfh
@@ -39,36 +39,54 @@ public final class Clownfish::String nickname Str
/** Return a String which holds a copy of the supplied UTF-8 character
* data after checking for validity.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert incremented String*
new_from_utf8(const char *utf8, size_t size);
/** Return a String which holds a copy of the supplied UTF-8 character
* data, skipping validity checks.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert incremented String*
new_from_trusted_utf8(const char *utf8, size_t size);
/** Initialize a String which holds a copy of the supplied UTF-8 character
* data, skipping validity checks.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert String*
init_from_trusted_utf8(String *self, const char *utf8, size_t size);
/** Return a String which assumes ownership of the supplied buffer
* containing UTF-8 character data after checking for validity.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert incremented String*
new_steal_utf8(char *utf8, size_t size);
/** Return a String which assumes ownership of the supplied buffer
* containing UTF-8 character data, skipping validity checks.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert incremented String*
new_steal_trusted_utf8(char *utf8, size_t size);
/** Initialize a String which assumes ownership of the supplied buffer
* containing UTF-8 character data, skipping validity checks.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert String*
init_steal_trusted_utf8(String *self, char *utf8, size_t size);
@@ -76,6 +94,9 @@ public final class Clownfish::String nickname Str
/** Return a String which wraps an external buffer containing UTF-8
* character data after checking for validity. The buffer must stay
* unchanged for the lifetime of the String.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert incremented String*
new_wrap_utf8(const char *utf8, size_t size);
@@ -83,6 +104,9 @@ public final class Clownfish::String nickname Str
/** Return a String which wraps an external buffer containing UTF-8
* character data, skipping validity checks. The buffer must stay
* unchanged for the lifetime of the String.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert incremented String*
new_wrap_trusted_utf8(const char *utf8, size_t size);
@@ -92,20 +116,27 @@ public final class Clownfish::String nickname Str
/** Initialize a String which wraps an external buffer containing UTF-8
* character data after checking for validity.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public inert String*
init_wrap_trusted_utf8(String *self, const char *utf8, size_t size);
/** Return a String which holds a single character.
+ *
+ * @param code_point Unicode code point of the character.
*/
public inert incremented String*
new_from_char(int32_t code_point);
/** Return a String with content expanded from a pattern and arguments
- * conforming to the spec defined by CharBuf.
+ * conforming to the spec defined by [](CharBuf.VCatF).
*
* Note: a user-supplied `pattern` string is a security hole
* and must not be allowed.
+ *
+ * @param pattern A format string.
*/
public inert incremented String*
newf(const char *pattern, ...);
@@ -120,24 +151,41 @@ public final class Clownfish::String nickname Str
/** Return the concatenation of the String and the supplied UTF-8
* character data after checking for validity.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public incremented String*
Cat_Utf8(String *self, const char *utf8, size_t size);
/** Return the concatenation of the String and the supplied UTF-8
* character data, skipping validity checks.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public incremented String*
Cat_Trusted_Utf8(String *self, const char *utf8, size_t size);
+ /** Extract a 64-bit integer from a decimal string. See [](.BaseX_To_I64)
+ * for details.
+ */
public int64_t
To_I64(String *self);
/** Extract a 64-bit integer from a variable-base stringified version.
+ * Expects an optional minus sign followed by base-x digits, stopping at
+ * any non-digit character. Returns zero if no digits are found. If the
+ * value exceeds the range of an `int64_t`, the result is undefined.
+ *
+ * @param base A base between 2 and 36.
*/
public int64_t
BaseX_To_I64(String *self, uint32_t base);
+ /** Convert a string to a floating-point number using the C library
+ * function `strtod`.
+ */
public double
To_F64(String *self);
@@ -146,7 +194,10 @@ public final class Clownfish::String nickname Str
public bool
Starts_With(String *self, String *prefix);
- /** Test whether the String starts with `prefix`.
+ /** Test whether the String starts with a prefix supplied as raw UTF-8.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public bool
Starts_With_Utf8(String *self, const char *utf8, size_t size);
@@ -156,7 +207,10 @@ public final class Clownfish::String nickname Str
public bool
Ends_With(String *self, String *suffix);
- /** Test whether the String ends with `suffix`.
+ /** Test whether the String ends with a suffix supplied as raw UTF-8.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public bool
Ends_With_Utf8(String *self, const char *utf8, size_t size);
@@ -166,13 +220,16 @@ public final class Clownfish::String nickname Str
public bool
Contains(String *self, String *substring);
- /** Test whether the String contains `substring`.
+ /** Test whether the String contains a substring supplied as raw UTF-8.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public bool
Contains_Utf8(String *self, const char *utf8, size_t size);
- /** Return a [](StringIterator) pointing to the first occurrence of the
- * substring within the String, or [](@null) if the substring does not
+ /** Return a [](StringIterator) pointing to the first occurrence of
+ * `substring` within the String, or [](@null) if the substring does not
* match.
*/
public incremented nullable StringIterator*
@@ -180,7 +237,10 @@ public final class Clownfish::String nickname Str
/** Return a [](StringIterator) pointing to the first occurrence of the
* substring within the String, or [](@null) if the substring does not
- * match.
+ * match. The substring is supplied as raw UTF-8.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public incremented nullable StringIterator*
Find_Utf8(String *self, const char *utf8, size_t size);
@@ -202,6 +262,7 @@ public final class Clownfish::String nickname Str
/** Return the internal backing array for the String if its internal
* encoding is UTF-8. If it is not encoded as UTF-8 throw an exception.
+ * The character data is not null-terminated.
*/
public const char*
Get_Ptr8(String *self);
@@ -241,33 +302,38 @@ public final class Clownfish::String nickname Str
To_String(String *self);
/** Remove Unicode whitespace characters from both top and tail.
+ * Whitespace is any character that has the Unicode property
+ * `White_Space`.
*/
public incremented String*
Trim(String *self);
- /** Remove leading Unicode whitespace.
+ /** Remove leading Unicode whitespace. Whitespace is any character
+ * that has the Unicode property `White_Space`.
*/
public incremented String*
Trim_Top(String *self);
- /** Remove trailing Unicode whitespace.
+ /** Remove trailing Unicode whitespace. Whitespace is any character
+ * that has the Unicode property `White_Space`.
*/
public incremented String*
Trim_Tail(String *self);
/** Return the Unicode code point located `tick` code points in from the
- * top. Return CFISH_STR_OOB if out of bounds.
+ * top. Return `CFISH_STR_OOB` if out of bounds.
*/
public int32_t
Code_Point_At(String *self, size_t tick);
/** Return the Unicode code point located `tick` code points counting
- * backwards from the end. Return CFISH_STR_OOB if out of bounds.
+ * backwards from the end. Return `CFISH_STR_OOB` if out of bounds.
*/
public int32_t
Code_Point_From(String *self, size_t tick);
/** Return a new String containing a copy of the specified substring.
+ *
* @param offset Offset from the top, in code points.
* @param len The desired length of the substring, in code points.
*/
@@ -299,6 +365,7 @@ public final class Clownfish::StringIterator nickname StrIter
new(String *string, size_t byte_offset);
/** Return the substring between the top and tail iterators.
+ *
* @param top Top iterator. Use start of string if [](@null).
* @param tail Tail iterator. Use end of string if [](@null).
*/
@@ -308,6 +375,8 @@ public final class Clownfish::StringIterator nickname StrIter
public incremented StringIterator*
Clone(StringIterator *self);
+ /** Assign the source string and current position of `other` to `self`.
+ */
public void
Assign(StringIterator *self, StringIterator *other);
@@ -328,18 +397,19 @@ public final class Clownfish::StringIterator nickname StrIter
Has_Prev(StringIterator *self);
/** Return the code point after the current position and advance the
- * iterator. Return CFISH_STR_OOB at the end of the string.
+ * iterator. Return `CFISH_STR_OOB` at the end of the string.
*/
public int32_t
Next(StringIterator *self);
/** Return the code point before the current position and go one step back.
- * Return CFISH_STR_OOB at the start of the string.
+ * Return `CFISH_STR_OOB` at the start of the string.
*/
public int32_t
Prev(StringIterator *self);
/** Skip code points.
+ *
* @param num The number of code points to skip.
* @return the number of code points actually skipped. This can be less
* than the requested number if the end of the string is reached.
@@ -348,6 +418,7 @@ public final class Clownfish::StringIterator nickname StrIter
Advance(StringIterator *self, size_t num);
/** Skip code points backward.
+ *
* @param num The number of code points to skip.
* @return the number of code points actually skipped. This can be less
* than the requested number if the start of the string is reached.
@@ -355,13 +426,17 @@ public final class Clownfish::StringIterator nickname StrIter
public size_t
Recede(StringIterator *self, size_t num);
- /** Skip whitespace.
+ /** Skip whitespace. Whitespace is any character that has the Unicode
+ * property `White_Space`.
+ *
* @return the number of code points skipped.
*/
public size_t
Skip_Whitespace(StringIterator *self);
- /** Skip whitespace backward.
+ /** Skip whitespace backward. Whitespace is any character that has the
+ * Unicode property `White_Space`.
+ *
* @return the number of code points skipped.
*/
public size_t
@@ -372,18 +447,25 @@ public final class Clownfish::StringIterator nickname StrIter
public bool
Starts_With(StringIterator *self, String *prefix);
- /** Test whether the content after the iterator starts with `prefix`.
+ /** Test whether the content after the iterator starts with a prefix
+ * supplied as raw UTF-8.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public bool
Starts_With_Utf8(StringIterator *self, const char *utf8, size_t size);
- /** Test whether the content before the iterator ends with
- * `suffix`.
+ /** Test whether the content before the iterator ends with `suffix`.
*/
public bool
Ends_With(StringIterator *self, String *suffix);
- /** Test whether the content before the iterator ends with `suffix`.
+ /** Test whether the content before the iterator ends with a suffix
+ * supplied as raw UTF-8.
+ *
+ * @param utf8 Pointer to UTF-8 character data.
+ * @param size Size of UTF-8 character data in bytes.
*/
public bool
Ends_With_Utf8(StringIterator *self, const char *utf8, size_t size);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/Util/Memory.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Util/Memory.cfh b/runtime/core/Clownfish/Util/Memory.cfh
index 69ae85f..d94cf9e 100644
--- a/runtime/core/Clownfish/Util/Memory.cfh
+++ b/runtime/core/Clownfish/Util/Memory.cfh
@@ -18,20 +18,20 @@ parcel Clownfish;
inert class Clownfish::Util::Memory {
- /** Attempt to allocate memory with malloc, but print an error and exit if the
- * call fails.
+ /** Attempt to allocate memory with malloc, but print an error and exit
+ * if the call fails.
*/
inert nullable void*
wrapped_malloc(size_t count);
- /** Attempt to allocate memory with calloc, but print an error and exit if the
- * call fails.
+ /** Attempt to allocate memory with calloc, but print an error and exit
+ * if the call fails.
*/
inert nullable void*
wrapped_calloc(size_t count, size_t size);
- /** Attempt to allocate memory with realloc, but print an error and exit if
- * the call fails.
+ /** Attempt to allocate memory with realloc, but print an error and exit
+ * if the call fails.
*/
inert nullable void*
wrapped_realloc(void *ptr, size_t size);
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/6210eac9/runtime/core/Clownfish/Vector.cfh
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Vector.cfh b/runtime/core/Clownfish/Vector.cfh
index 9271988..3f902f9 100644
--- a/runtime/core/Clownfish/Vector.cfh
+++ b/runtime/core/Clownfish/Vector.cfh
@@ -24,10 +24,16 @@ public final class Clownfish::Vector nickname Vec inherits Clownfish::Obj {
size_t size;
size_t cap;
+ /** Return a new Vector.
+ *
+ * @param capacity Initial number of elements that the object will be able
+ * to hold before reallocation.
+ */
public inert incremented Vector*
new(size_t capacity = 0);
- /**
+ /** Initialize a Vector.
+ *
* @param capacity Initial number of elements that the object will be able
* to hold before reallocation.
*/
@@ -48,6 +54,8 @@ public final class Clownfish::Vector nickname Vec inherits Clownfish::Obj {
Push_All(Vector *self, Vector *other);
/** Pop an item off of the end of a Vector.
+ *
+ * @return the element or [](@null) if the Vector is empty.
*/
public incremented nullable Obj*
Pop(Vector *self);
@@ -63,13 +71,14 @@ public final class Clownfish::Vector nickname Vec inherits Clownfish::Obj {
public void
Insert_All(Vector *self, size_t tick, Vector *other);
- /** Ensure that the Vector has room for at least `capacity`
- * elements.
+ /** Ensure that the Vector has room for at least `capacity` elements.
*/
void
Grow(Vector *self, size_t capacity);
/** Fetch the element at `tick`.
+ *
+ * @return the element or [](@null) if `tick` is out of bounds.
*/
public nullable Obj*
Fetch(Vector *self, size_t tick);
@@ -82,13 +91,14 @@ public final class Clownfish::Vector nickname Vec inherits Clownfish::Obj {
/** Replace an element in the Vector with NULL and return it.
*
- * @return whatever was stored at `tick`.
+ * @return the element stored at `tick` or [](@null) if `tick` is out of
+ * bounds.
*/
public incremented nullable Obj*
Delete(Vector *self, size_t tick);
- /** Remove `length` elements from the vector, starting at
- * `offset`. Move elements over to fill in the gap.
+ /** Remove `length` elements from the vector, starting at `offset`.
+ * Move elements over to fill in the gap.
*/
public void
Excise(Vector *self, size_t offset, size_t length);
@@ -106,8 +116,8 @@ public final class Clownfish::Vector nickname Vec inherits Clownfish::Obj {
Sort(Vector *self);
/** Set the size for the Vector. If the new size is larger than the
- * current size, grow the object to accommodate NULL elements; if smaller
- * than the current size, decrement and discard truncated elements.
+ * current size, grow the object to accommodate [](@null) elements; if
+ * smaller than the current size, decrement and discard truncated elements.
*/
public void
Resize(Vector *self, size_t size);
@@ -117,12 +127,13 @@ public final class Clownfish::Vector nickname Vec inherits Clownfish::Obj {
public void
Clear(Vector *self);
- /** Accessor for `size` member.
+ /** Return the size of the Vector.
*/
public size_t
Get_Size(Vector *self);
- /** Accessor for `capacity` member.
+ /** Return the capacity of the Vector. This is the maximum number of
+ * elements the Vector can hold without reallocation.
*/
size_t
Get_Capacity(Vector *self);