From bba5e2c791b14b30ce74b40dc8f454b9d20d7221 Mon Sep 17 00:00:00 2001
From: Alvin <154572722+alvinng4@users.noreply.github.com>
Date: Mon, 29 Dec 2025 21:47:34 +0800
Subject: [PATCH] [Website] update api docs
---
README.md | 2 +
.../docs/API/call_stack_management.mdx | 57 ++++---
website/content/docs/API/inline_logging.mdx | 143 ++++++++++++++++++
3 files changed, 177 insertions(+), 25 deletions(-)
create mode 100644 website/content/docs/API/inline_logging.mdx
diff --git a/README.md b/README.md
index 69e12db..2dde613 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,6 @@
# c_traceback
A colorful, lightweight error-propagation framework for C.
+Website (in development): [https://www.alvinng4.github.io/c_traceback/](https://www.alvinng4.github.io/c_traceback/)
+
This library is in early development. Come back later!
diff --git a/website/content/docs/API/call_stack_management.mdx b/website/content/docs/API/call_stack_management.mdx
index 6d82aa5..04f88e7 100644
--- a/website/content/docs/API/call_stack_management.mdx
+++ b/website/content/docs/API/call_stack_management.mdx
@@ -7,13 +7,17 @@ import ParamsTable from "components/params-table.tsx";
# Call Stack Management
In order to obtain the traceback in run time, we need to actively manage the call stack.
-It is not difficult, but functions or code blocks have to be wrapped with a macro, which
-is quite verbose.
+Unfortunately, C doesn't provide an easy way to do this. Therefore, we will have to wrap
+function calls or code blocks with a macro. While this approach can be quite verbose, it
+is what makes our library possible.
## API
### `CTB_WRAP`
Wrapper macro for expression to automatically manage call stack frames.
+```c
+CTB_WRAP(expr)
+```
#### Parameters
+#### Expands to
+```c
+do \
+{ \
+ ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #expr); \
+ (expr); \
+ ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #expr); \
+} while (0)
+```
+
#### Usage
```c
int function_a(void)
{
- CTB_WRAP(function_b()); // Wrap a function call
+ CTB_WRAP(function_b()); // Wraps a function call
}
int function_b(void)
{
int i = 0;
- CTB_WRAP(i = 2); // Wrap an assignment
+ CTB_WRAP(i = 2); // Wraps an assignment
}
```
-#### Expands to
-```c
-do
-{
- ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #expr);
- (expr);
- ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #expr);
-} while (0)
-```
-
### `CTB_Block`
Wrapper macro for a code block to automatically manage call stack frames.
+```c
+CTB_BLOCK(...)
+```
#### Parameters
+#### Expands to
+```c
+do \
+{ \
+ ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__); \
+ __VA_ARGS__ \
+ ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__); \
+} while (0)
+```
+
#### Usage
```c
int function_a(void)
{
- /* Wrap a code block */
+ /* Wraps a code block */
CTB_BLOCK(
int i = 0;
if (i == 0)
@@ -72,14 +89,4 @@ int function_a(void)
// Note: i is not accessible here
// printf("%d", i); <-- Illegal!
}
-```
-
-#### Expands to
-```c
-do
-{
- ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__);
- __VA_ARGS__
- ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__);
-} while (0)
```
\ No newline at end of file
diff --git a/website/content/docs/API/inline_logging.mdx b/website/content/docs/API/inline_logging.mdx
new file mode 100644
index 0000000..c77b55d
--- /dev/null
+++ b/website/content/docs/API/inline_logging.mdx
@@ -0,0 +1,143 @@
+---
+title: Inline Logging
+---
+
+import ParamsTable from "components/params-table.tsx";
+
+# Inline Logging
+
+Sometimes, we just want to log a simple message without the full traceback.
+In this case, we can use the inline logging API.
+
+## API
+
+### `CTB_LOG_ERROR_INLINE`
+Wrapper for logging an error to stderr without stacktrace.
+```c
+CTB_LOG_ERROR_INLINE(ctb_error, msg, ...)
+```
+
+Logging an inline error has no effect on the context / call stack. It only logs an error message.
+
+#### Parameters
+
+
+#### Expands to
+```c
+do \
+{ \
+ ctb_log_error_inline( \
+ __FILE__, __LINE__, __func__, ctb_error, msg, __VA_ARGS__ \
+ ); \
+} while (0)
+```
+
+#### Usage
+```c
+double division(double x, double y)
+{
+ if (y == 0)
+ {
+ CTB_LOG_ERROR_INLINE(
+ CTB_ZERO_DIVISION_ERROR,
+ "y cannot be zero! Received: %lf",
+ y
+ );
+ return 0.0;
+ }
+ return x / y;
+}
+```
+Output:
+```ansi
+[1;31mZeroDivisionError:[0m [38;5;240mFile "[0m[38;5;240m/home/alvinng/Desktop/c_trackback/examples/[0m[1;36mexample.c[0m[38;5;240m", line[0m [1;36m19[0m [38;5;240min[0m [1;36mdivision[0m:
+ [0;31my cannot be zero! Received: 0.000000[0m
+```
+
+### `CTB_LOG_WARNING_INLINE`
+Wrapper for logging a warning to stderr without stacktrace.
+```c
+CTB_LOG_WARNING_INLINE(ctb_warning, msg, ...)
+```
+
+#### Parameters
+
+
+#### Expands to
+```c
+do \
+{ \
+ ctb_log_warning_inline( \
+ __FILE__, __LINE__, __func__, ctb_warning, msg, __VA_ARGS__ \
+ ); \
+} while (0)
+```
+
+#### Usage
+```c
+double some_function(void)
+{
+ CTB_LOG_WARNING_INLINE(
+ CTB_DEPRECATION_WARNING,
+ "Function \"%s\" is deprecated. It will be removed in the next version.",
+ __func__
+ );
+
+ /* Do something */
+
+ return;
+}
+```
+Output:
+```ansi
+[1;33mDeprecationWarning:[0m [38;5;240mFile "[0m[38;5;240m/home/alvinng/Desktop/c_trackback/examples/[0m[1;36mexample.c[0m[38;5;240m", line[0m [1;36m17[0m [38;5;240min[0m [1;36msome_function[0m:
+ [5;33mFunction "some_function" is deprecated. It will be removed in the next version.[0m
+```
+
+### `CTB_LOG_MESSAGE_INLINE`
+Wrapper for logging a message to stdout without stacktrace.
+```c
+CTB_LOG_MESSAGE_INLINE(msg, ...)
+```
+
+#### Parameters
+
+
+#### Expands to
+```c
+do \
+{ \
+ ctb_log_message_inline(__FILE__, __LINE__, __func__, msg, __VA_ARGS__); \
+} while (0)
+```
+
+#### Usage
+```c
+void inline_message(int i)
+{
+ CTB_LOG_MESSAGE_INLINE("(Test %d) Hello, world! :)", i);
+}
+```
+
+Output:
+```ansi
+[1;95mMessage:[0m [38;5;240mFile "[0m[38;5;240m/home/alvinng/Desktop/c_trackback/examples/[0m[1;36mexample.c[0m[38;5;240m", line[0m [1;36m75[0m [38;5;240min[0m [1;36minline_message[0m:
+ [0;35m(Test 0) Hello, world! :)[0m
+```
\ No newline at end of file