Skip to content

Try to use clearer language in buffer docs #1738

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bakpakin merged 2 commits into from
Apr 20, 2026
+16 −11
Merged

Try to use clearer language in buffer docs #1738

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
90e78c7
Clarify buffer limits in docs
sarna Apr 14, 2026
a68edd1
Wording
sarna Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions src/core/buffer.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,8 +272,8 @@ JANET_CORE_FN(cfun_buffer_trim,

JANET_CORE_FN(cfun_buffer_u8,
"(buffer/push-byte buffer & xs)",
"Append bytes to a buffer. Will expand the buffer as necessary. "
"Returns the modified buffer. Will throw an error if the buffer overflows.") {
"Append bytes to a buffer. Returns the modified buffer. "
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
int32_t i;
janet_arity(argc, 1, -1);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
Expand All @@ -286,8 +286,8 @@ JANET_CORE_FN(cfun_buffer_u8,
JANET_CORE_FN(cfun_buffer_word,
"(buffer/push-word buffer & xs)",
"Append machine words to a buffer. The 4 bytes of the integer are appended "
"in twos complement, little endian order, unsigned for all x. Returns the modified buffer. Will "
"throw an error if the buffer overflows.") {
"in twos complement, little endian order, unsigned for all x. Returns the modified buffer. "
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
int32_t i;
janet_arity(argc, 1, -1);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
Expand All @@ -306,7 +306,7 @@ JANET_CORE_FN(cfun_buffer_chars,
"Push byte sequences onto the end of a buffer. "
"Will accept any of strings, keywords, symbols, and buffers. "
"Returns the modified buffer. "
"Will throw an error if the buffer overflows.") {
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
int32_t i;
janet_arity(argc, 1, -1);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
Expand Down Expand Up @@ -368,7 +368,8 @@ static void reverse_u64(uint8_t bytes[8]) {
JANET_CORE_FN(cfun_buffer_push_uint16,
"(buffer/push-uint16 buffer order data)",
"Push a 16 bit unsigned integer data onto the end of the buffer. "
"Returns the modified buffer.") {
"Returns the modified buffer."
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
janet_fixarity(argc, 3);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
int reverse = should_reverse_bytes(argv, 1);
Expand All @@ -387,7 +388,8 @@ JANET_CORE_FN(cfun_buffer_push_uint16,
JANET_CORE_FN(cfun_buffer_push_uint32,
"(buffer/push-uint32 buffer order data)",
"Push a 32 bit unsigned integer data onto the end of the buffer. "
"Returns the modified buffer.") {
"Returns the modified buffer."
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
janet_fixarity(argc, 3);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
int reverse = should_reverse_bytes(argv, 1);
Expand All @@ -403,7 +405,8 @@ JANET_CORE_FN(cfun_buffer_push_uint32,
JANET_CORE_FN(cfun_buffer_push_uint64,
"(buffer/push-uint64 buffer order data)",
"Push a 64 bit unsigned integer data onto the end of the buffer. "
"Returns the modified buffer.") {
"Returns the modified buffer."
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
janet_fixarity(argc, 3);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
int reverse = should_reverse_bytes(argv, 1);
Expand All @@ -419,7 +422,8 @@ JANET_CORE_FN(cfun_buffer_push_uint64,
JANET_CORE_FN(cfun_buffer_push_float32,
"(buffer/push-float32 buffer order data)",
"Push the underlying bytes of a 32 bit float data onto the end of the buffer. "
"Returns the modified buffer.") {
"Returns the modified buffer."
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
janet_fixarity(argc, 3);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
int reverse = should_reverse_bytes(argv, 1);
Expand All @@ -435,7 +439,8 @@ JANET_CORE_FN(cfun_buffer_push_float32,
JANET_CORE_FN(cfun_buffer_push_float64,
"(buffer/push-float64 buffer order data)",
"Push the underlying bytes of a 64 bit float data onto the end of the buffer. "
"Returns the modified buffer.") {
"Returns the modified buffer."
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
janet_fixarity(argc, 3);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
int reverse = should_reverse_bytes(argv, 1);
Expand Down Expand Up @@ -488,7 +493,7 @@ JANET_CORE_FN(cfun_buffer_push,
"push the byte if x is an integer, otherwise push the bytesequence to the buffer. "
"Thus, this function behaves like both `buffer/push-string` and `buffer/push-byte`. "
"Returns the modified buffer. "
"Will throw an error if the buffer overflows.") {
"Expands the buffer as necessary. Throws an error if size limit is exceeded.") {
janet_arity(argc, 1, -1);
JanetBuffer *buffer = janet_getbuffer(argv, 0);
buffer_push_impl(buffer, argv, 1, argc);
Expand Down
Loading