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 <wellnho...@aevum.de> Authored: Wed Feb 3 15:03:02 2016 +0100 Committer: Nick Wellnhofer <wellnho...@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);