Skip to content

Commit 21a3c49

Browse files
alvinng4alvinng4
committed
[Website] update api docs
1 parent 1d7863d commit 21a3c49

3 files changed

Lines changed: 177 additions & 25 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
# c_traceback
22
A colorful, lightweight error-propagation framework for C.
33

4+
Website (in development): [https://www.alvinng4.github.io/c_traceback/](https://www.alvinng4.github.io/c_traceback/)
5+
46
This library is in early development. Come back later!

‎website/content/docs/API/call_stack_management.mdx‎

Lines changed: 32 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,17 @@ import ParamsTable from "components/params-table.tsx";
77
# Call Stack Management
88

99
In order to obtain the traceback in run time, we need to actively manage the call stack.
10-
It is not difficult, but functions or code blocks have to be wrapped with a macro, which
11-
is quite verbose.
10+
Unfortunately, C doesn't provide an easy way to do this. Therefore, we will have to wrap
11+
function calls or code blocks with a macro. While this approach can be quite verbose, it
12+
is what makes our library possible.
1213

1314
## API
1415

1516
### `CTB_WRAP` <Badge text="Macro" />
1617
Wrapper macro for expression to automatically manage call stack frames.
18+
```c
19+
CTB_WRAP(expr)
20+
```
1721
1822
#### Parameters
1923
<ParamsTable
@@ -22,32 +26,35 @@ Wrapper macro for expression to automatically manage call stack frames.
2226
]}
2327
/>
2428
29+
#### Expands to
30+
```c
31+
do \
32+
{ \
33+
ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #expr); \
34+
(expr); \
35+
ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #expr); \
36+
} while (0)
37+
```
38+
2539
#### Usage
2640
```c
2741
int function_a(void)
2842
{
29-
CTB_WRAP(function_b()); // Wrap a function call
43+
CTB_WRAP(function_b()); // Wraps a function call
3044
}
3145

3246
int function_b(void)
3347
{
3448
int i = 0;
35-
CTB_WRAP(i = 2); // Wrap an assignment
49+
CTB_WRAP(i = 2); // Wraps an assignment
3650
}
3751
```
3852
39-
#### Expands to
40-
```c
41-
do
42-
{
43-
ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #expr);
44-
(expr);
45-
ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #expr);
46-
} while (0)
47-
```
48-
4953
### `CTB_Block` <Badge text="Macro" />
5054
Wrapper macro for a code block to automatically manage call stack frames.
55+
```c
56+
CTB_BLOCK(...)
57+
```
5158

5259
#### Parameters
5360
<ParamsTable
@@ -56,11 +63,21 @@ Wrapper macro for a code block to automatically manage call stack frames.
5663
]}
5764
/>
5865

66+
#### Expands to
67+
```c
68+
do \
69+
{ \
70+
ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__); \
71+
__VA_ARGS__ \
72+
ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__); \
73+
} while (0)
74+
```
75+
5976
#### Usage
6077
```c
6178
int function_a(void)
6279
{
63-
/* Wrap a code block */
80+
/* Wraps a code block */
6481
CTB_BLOCK(
6582
int i = 0;
6683
if (i == 0)
@@ -72,14 +89,4 @@ int function_a(void)
7289
// Note: i is not accessible here
7390
// printf("%d", i); <-- Illegal!
7491
}
75-
```
76-
77-
#### Expands to
78-
```c
79-
do
80-
{
81-
ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__);
82-
__VA_ARGS__
83-
ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__);
84-
} while (0)
8592
```

‎website/content/docs/API/inline_logging.mdx‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Inline Logging
3+
---
4+
5+
import ParamsTable from "components/params-table.tsx";
6+
7+
# Inline Logging
8+
9+
Sometimes, we just want to log a simple message without the full traceback.
10+
In this case, we can use the inline logging API.
11+
12+
## API
13+
14+
### `CTB_LOG_ERROR_INLINE` <Badge text="Macro" />
15+
Wrapper for logging an error to stderr without stacktrace.
16+
```c
17+
CTB_LOG_ERROR_INLINE(ctb_error, msg, ...)
18+
```
19+
20+
<Callout type="warning">Logging an inline error has no effect on the context / call stack. It only logs an error message.</Callout>
21+
22+
#### Parameters
23+
<ParamsTable
24+
params={[
25+
{ name: "ctb_error", type: "CTB_Error", desc: "The error type." },
26+
{ name: "msg", type: "const char *", desc: "Error message." },
27+
{ name: "...", type: "N/A", desc: "Additional arguments for formatting the message." },
28+
]}
29+
/>
30+
31+
#### Expands to
32+
```c
33+
do \
34+
{ \
35+
ctb_log_error_inline( \
36+
__FILE__, __LINE__, __func__, ctb_error, msg, __VA_ARGS__ \
37+
); \
38+
} while (0)
39+
```
40+
41+
#### Usage
42+
```c
43+
double division(double x, double y)
44+
{
45+
if (y == 0)
46+
{
47+
CTB_LOG_ERROR_INLINE(
48+
CTB_ZERO_DIVISION_ERROR,
49+
"y cannot be zero! Received: %lf",
50+
y
51+
);
52+
return 0.0;
53+
}
54+
return x / y;
55+
}
56+
```
57+
Output:
58+
```ansi
59+
ZeroDivisionError: File "/home/alvinng/Desktop/c_trackback/examples/example.c", line 19 in division:
60+
y cannot be zero! Received: 0.000000
61+
```
62+
63+
### `CTB_LOG_WARNING_INLINE` <Badge text="Macro" />
64+
Wrapper for logging a warning to stderr without stacktrace.
65+
```c
66+
CTB_LOG_WARNING_INLINE(ctb_warning, msg, ...)
67+
```
68+
69+
#### Parameters
70+
<ParamsTable
71+
params={[
72+
{ name: "ctb_warning", type: "CTB_Warning", desc: "The warning type." },
73+
{ name: "msg", type: "const char *", desc: "Warning message." },
74+
{ name: "...", type: "N/A", desc: "Additional arguments for formatting the message." },
75+
]}
76+
/>
77+
78+
#### Expands to
79+
```c
80+
do \
81+
{ \
82+
ctb_log_warning_inline( \
83+
__FILE__, __LINE__, __func__, ctb_warning, msg, __VA_ARGS__ \
84+
); \
85+
} while (0)
86+
```
87+
88+
#### Usage
89+
```c
90+
double some_function(void)
91+
{
92+
CTB_LOG_WARNING_INLINE(
93+
CTB_DEPRECATION_WARNING,
94+
"Function \"%s\" is deprecated. It will be removed in the next version.",
95+
__func__
96+
);
97+
98+
/* Do something */
99+
100+
return;
101+
}
102+
```
103+
Output:
104+
```ansi
105+
DeprecationWarning: File "/home/alvinng/Desktop/c_trackback/examples/example.c", line 17 in some_function:
106+
Function "some_function" is deprecated. It will be removed in the next version.
107+
```
108+
109+
### `CTB_LOG_MESSAGE_INLINE` <Badge text="Macro" />
110+
Wrapper for logging a message to stdout without stacktrace.
111+
```c
112+
CTB_LOG_MESSAGE_INLINE(msg, ...)
113+
```
114+
115+
#### Parameters
116+
<ParamsTable
117+
params={[
118+
{ name: "msg", type: "const char *", desc: "Message." },
119+
{ name: "...", type: "N/A", desc: "Additional arguments for formatting the message." },
120+
]}
121+
/>
122+
123+
#### Expands to
124+
```c
125+
do \
126+
{ \
127+
ctb_log_message_inline(__FILE__, __LINE__, __func__, msg, __VA_ARGS__); \
128+
} while (0)
129+
```
130+
131+
#### Usage
132+
```c
133+
void inline_message(int i)
134+
{
135+
CTB_LOG_MESSAGE_INLINE("(Test %d) Hello, world! :)", i);
136+
}
137+
```
138+
139+
Output:
140+
```ansi
141+
Message: File "/home/alvinng/Desktop/c_trackback/examples/example.c", line 75 in inline_message:
142+
(Test 0) Hello, world! :)
143+
```

0 commit comments

Comments
 (0)