Skip to content

Commit 6480cb0

Browse files
maia-smaia-s
committed
link more SDL syms in docs
1 parent 951e3e2 commit 6480cb0

26 files changed

+452
-421
lines changed

‎sdl3-sys-gen/src/emit.rs

+46-15
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@ pub const fn is_valid_ident(s: &str) -> bool {
2929
matches!(s.as_bytes()[0], b'a'..=b'z' | b'A'..=b'Z' | b'_')
3030
}
3131

32+
pub fn skip_doc_link_sym(s: &str) -> bool {
33+
matches!(s, "SDL_image" | "SDL_MAIN_USE_CALLBACKS")
34+
}
35+
3236
fn emit_extern_start(ctx: &mut EmitContext, abi: &Option<FnAbi>, for_fn_ptr: bool) -> EmitResult {
3337
if let Some(abi) = &abi {
3438
match abi.ident.as_str() {
@@ -219,17 +223,19 @@ impl DocComment {
219223
if i < i0 {
220224
continue;
221225
}
222-
write!(patched, "{}", &line[i0..i])?;
223226
quoted += line[i0..i].chars().filter(|c| *c == '`').count();
224-
i0 = i;
225227

226-
if quoted & 1 == 0 {
228+
if (quoted & 1 == 0)
229+
|| (line.as_bytes().get(i.wrapping_sub(1)).copied() == Some(b'`')
230+
&& line.as_bytes().get(i.wrapping_sub(2)).copied() != Some(b'['))
231+
{
227232
if (line[i..].starts_with("https://") || line[i..].starts_with("http://"))
228233
&& (i == 0
229234
|| line.as_bytes()[i - 1].is_ascii_whitespace()
230235
|| (line.as_bytes()[i - 1] == b'('
231236
&& line.as_bytes().get(i.saturating_sub(2)).copied() != Some(b']')))
232237
{
238+
write!(patched, "{}", &line[i0..i])?;
233239
i0 = i + line[i..]
234240
.find(|c: char| {
235241
c.is_ascii_whitespace()
@@ -241,26 +247,51 @@ impl DocComment {
241247
} else if line[i..].starts_with("SDL_")
242248
&& (i == 0
243249
|| line.as_bytes()[i - 1].is_ascii_whitespace()
244-
|| line.as_bytes()[i - 1] == b'(')
250+
|| line.as_bytes()[i - 1] == b'('
251+
|| (line.as_bytes()[i - 1] == b'`'
252+
&& line.as_bytes().get(i.wrapping_sub(2)).copied() != Some(b'[')))
245253
{
246-
let end = i + line[i..]
254+
let mut end = i + line[i..]
247255
.find(|c: char| !c.is_ascii_alphanumeric() && c != '_')
248256
.unwrap_or(line.len() - i);
249-
if line.len() == end
250-
|| line.as_bytes()[end].is_ascii_whitespace()
251-
|| matches!(line.as_bytes()[end], b')' | b',' | b'.' | b';')
252-
|| (line.as_bytes()[end] == b'('
253-
&& line.as_bytes().get(end + 1).copied() == Some(b')'))
257+
if end > i + 4
258+
&& !skip_doc_link_sym(&line[i..end])
259+
&& (line.len() == end
260+
|| line.as_bytes()[end].is_ascii_whitespace()
261+
|| matches!(
262+
line.as_bytes()[end],
263+
b')' | b',' | b'.' | b';' | b':' | b'`'
264+
)
265+
|| (line.as_bytes()[end] == b'('
266+
&& line.as_bytes().get(end + 1).copied() == Some(b')')))
267+
&& (quoted & 1 == 0 || line.as_bytes()[end] == b'`')
254268
{
255-
i0 = end;
256-
if line.as_bytes().get(i0).copied() == Some(b'(')
257-
&& line.as_bytes().get(i0 + 1).copied() == Some(b')')
269+
if line.as_bytes().get(end).copied() == Some(b'(')
270+
&& line.as_bytes().get(end + 1).copied() == Some(b')')
258271
{
259-
i0 += 2;
272+
end += 2;
273+
}
274+
if quoted & 1 == 0 {
275+
write!(patched, "{}", &line[i0..i])?;
276+
write!(patched, "[`{}`]", &line[i..end])?;
277+
i0 = end;
278+
} else {
279+
write!(patched, "{}", &line[i0..i - 1])?;
280+
write!(patched, "[{}]", &line[i - 1..end + 1])?;
281+
i0 = end + 1;
282+
quoted += 1;
260283
}
261-
write!(patched, "[`{}`]", &line[i..i0])?;
284+
} else {
285+
write!(patched, "{}", &line[i0..i])?;
286+
i0 = i;
262287
}
288+
} else {
289+
write!(patched, "{}", &line[i0..i])?;
290+
i0 = i;
263291
}
292+
} else {
293+
write!(patched, "{}", &line[i0..i])?;
294+
i0 = i;
264295
}
265296
}
266297
write!(patched, "{}", &line[i0..])?;

‎sdl3-sys/src/generated/audio.rs

+4-4
Original file line numberDiff line numberDiff line change
@@ -737,8 +737,8 @@ extern "C" {
737737
/// function).
738738
///
739739
/// If you don't care about opening a specific device, pass a `devid` of either
740-
/// `SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK` or
741-
/// `SDL_AUDIO_DEVICE_DEFAULT_RECORDING`. In this case, SDL will try to pick
740+
/// [`SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK`] or
741+
/// [`SDL_AUDIO_DEVICE_DEFAULT_RECORDING`]. In this case, SDL will try to pick
742742
/// the most reasonable default, and may also switch between physical devices
743743
/// seamlessly later, if the most reasonable default changes during the
744744
/// lifetime of this opened device (user changed the default in the OS's system
@@ -2261,8 +2261,8 @@ extern "C" {
22612261
/// problematic files in the wild that cause issues with strict decoders. To
22622262
/// provide compatibility with these files, this decoder is lenient in regards
22632263
/// to the truncation of the file, the fact chunk, and the size of the RIFF
2264-
/// chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
2265-
/// `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
2264+
/// chunk. The hints [`SDL_HINT_WAVE_RIFF_CHUNK_SIZE`],
2265+
/// [`SDL_HINT_WAVE_TRUNCATION`], and [`SDL_HINT_WAVE_FACT_CHUNK`] can be used to
22662266
/// tune the behavior of the loading process.
22672267
///
22682268
/// Any file that is invalid (due to truncation, corruption, or wrong values in

‎sdl3-sys/src/generated/blendmode.rs

+7-7
Original file line numberDiff line numberDiff line change
@@ -264,20 +264,20 @@ extern "C" {
264264
/// enumeration.
265265
///
266266
/// - **direct3d**: Supports all operations with all factors. However, some
267-
/// factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
268-
/// `SDL_BLENDOPERATION_MAXIMUM`.
267+
/// factors produce unexpected results with [`SDL_BLENDOPERATION_MINIMUM`] and
268+
/// [`SDL_BLENDOPERATION_MAXIMUM`].
269269
/// - **direct3d11**: Same as Direct3D 9.
270-
/// - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
270+
/// - **opengl**: Supports the [`SDL_BLENDOPERATION_ADD`] operation with all
271271
/// factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly here.
272-
/// - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
273-
/// `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT`
272+
/// - **opengles2**: Supports the [`SDL_BLENDOPERATION_ADD`],
273+
/// [`SDL_BLENDOPERATION_SUBTRACT`], [`SDL_BLENDOPERATION_REV_SUBTRACT`]
274274
/// operations with all factors.
275275
/// - **psp**: No custom blend mode support.
276276
/// - **software**: No custom blend mode support.
277277
///
278278
/// Some renderers do not provide an alpha component for the default render
279-
/// target. The `SDL_BLENDFACTOR_DST_ALPHA` and
280-
/// `SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA` factors do not have an effect in this
279+
/// target. The [`SDL_BLENDFACTOR_DST_ALPHA`] and
280+
/// [`SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA`] factors do not have an effect in this
281281
/// case.
282282
///
283283
/// ### Arguments

‎sdl3-sys/src/generated/events.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -1886,14 +1886,14 @@ extern "C" {
18861886
///
18871887
/// `action` may be any of the following:
18881888
///
1889-
/// - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of the
1889+
/// - [`SDL_ADDEVENT`]: up to `numevents` events will be added to the back of the
18901890
/// event queue.
1891-
/// - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
1891+
/// - [`SDL_PEEKEVENT`]: `numevents` events at the front of the event queue,
18921892
/// within the specified minimum and maximum type, will be returned to the
18931893
/// caller and will _not_ be removed from the queue. If you pass NULL for
18941894
/// `events`, then `numevents` is ignored and the total number of matching
18951895
/// events will be returned.
1896-
/// - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
1896+
/// - [`SDL_GETEVENT`]: up to `numevents` events at the front of the event queue,
18971897
/// within the specified minimum and maximum type, will be returned to the
18981898
/// caller and will be removed from the queue.
18991899
///

‎sdl3-sys/src/generated/gamepad.rs

+10-10
Original file line numberDiff line numberDiff line change
@@ -1169,15 +1169,15 @@ extern "C" {
11691169
///
11701170
/// The following read-only properties are provided by SDL:
11711171
///
1172-
/// - `SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN`: true if this gamepad has an LED
1172+
/// - [`SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN`]: true if this gamepad has an LED
11731173
/// that has adjustable brightness
1174-
/// - `SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN`: true if this gamepad has an LED
1174+
/// - [`SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN`]: true if this gamepad has an LED
11751175
/// that has adjustable color
1176-
/// - `SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN`: true if this gamepad has a
1176+
/// - [`SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN`]: true if this gamepad has a
11771177
/// player LED
1178-
/// - `SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN`: true if this gamepad has
1178+
/// - [`SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN`]: true if this gamepad has
11791179
/// left/right rumble
1180-
/// - `SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this gamepad has
1180+
/// - [`SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN`]: true if this gamepad has
11811181
/// simple trigger rumble
11821182
///
11831183
/// ### Arguments
@@ -1439,7 +1439,7 @@ extern "C" {
14391439
/// - `gamepad`: the gamepad object to query.
14401440
/// ### Return value
14411441
/// Returns the connection state on success or
1442-
/// `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call [`SDL_GetError()`]
1442+
/// [`SDL_JOYSTICK_CONNECTION_INVALID`] on failure; call [`SDL_GetError()`]
14431443
/// for more information.
14441444
///
14451445
/// ### Availability
@@ -1590,7 +1590,7 @@ extern "C" {
15901590
/// - `str`: string representing a [`SDL_GamepadType`] type.
15911591
/// ### Return value
15921592
/// Returns the [`SDL_GamepadType`] enum corresponding to the input string, or
1593-
/// `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found.
1593+
/// [`SDL_GAMEPAD_TYPE_UNKNOWN`] if no match was found.
15941594
///
15951595
/// ### Availability
15961596
/// This function is available since SDL 3.1.3.
@@ -1627,14 +1627,14 @@ extern "C" {
16271627
/// [`SDL_Gamepad`] mappings in your own code.
16281628
///
16291629
/// Note specially that "righttrigger" and "lefttrigger" map to
1630-
/// `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`,
1630+
/// [`SDL_GAMEPAD_AXIS_RIGHT_TRIGGER`] and [`SDL_GAMEPAD_AXIS_LEFT_TRIGGER`],
16311631
/// respectively.
16321632
///
16331633
/// ### Arguments
16341634
/// - `str`: string representing a [`SDL_Gamepad`] axis.
16351635
/// ### Return value
16361636
/// Returns the [`SDL_GamepadAxis`] enum corresponding to the input string, or
1637-
/// `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
1637+
/// [`SDL_GAMEPAD_AXIS_INVALID`] if no match was found.
16381638
///
16391639
/// ### Availability
16401640
/// This function is available since SDL 3.1.3.
@@ -1726,7 +1726,7 @@ extern "C" {
17261726
/// - `str`: string representing a [`SDL_Gamepad`] axis.
17271727
/// ### Return value
17281728
/// Returns the [`SDL_GamepadButton`] enum corresponding to the input string, or
1729-
/// `SDL_GAMEPAD_BUTTON_INVALID` if no match was found.
1729+
/// [`SDL_GAMEPAD_BUTTON_INVALID`] if no match was found.
17301730
///
17311731
/// ### Availability
17321732
/// This function is available since SDL 3.1.3.

‎sdl3-sys/src/generated/gpu.rs

+10-10
Original file line numberDiff line numberDiff line change
@@ -3625,31 +3625,31 @@ extern "C" {
36253625
///
36263626
/// These are the supported properties:
36273627
///
3628-
/// - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode
3628+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`]: enable debug mode
36293629
/// properties and validations, defaults to true.
3630-
/// - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer
3630+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`]: enable to prefer
36313631
/// energy efficiency over maximum GPU performance, defaults to false.
3632-
/// - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to
3632+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`]: the name of the GPU driver to
36333633
/// use, if a specific one is desired.
36343634
///
36353635
/// These are the current shader format properties:
36363636
///
3637-
/// - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to
3637+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`]: The app is able to
36383638
/// provide shaders for an NDA platform.
3639-
/// - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to
3639+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`]: The app is able to
36403640
/// provide SPIR-V shaders if applicable.
3641-
/// - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to
3641+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`]: The app is able to
36423642
/// provide DXBC shaders if applicable
3643-
/// `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to
3643+
/// [`SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`]: The app is able to
36443644
/// provide DXIL shaders if applicable.
3645-
/// - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to
3645+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`]: The app is able to
36463646
/// provide MSL shaders if applicable.
3647-
/// - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to
3647+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`]: The app is able to
36483648
/// provide Metal shader libraries if applicable.
36493649
///
36503650
/// With the D3D12 renderer:
36513651
///
3652-
/// - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING`: the prefix to
3652+
/// - [`SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING`]: the prefix to
36533653
/// use for all vertex semantics, default is "TEXCOORD".
36543654
///
36553655
/// ### Arguments

‎sdl3-sys/src/generated/haptic.rs

+10-10
Original file line numberDiff line numberDiff line change
@@ -597,10 +597,10 @@ pub struct SDL_HapticPeriodic {
597597
///
598598
/// The struct handles the following effects:
599599
///
600-
/// - SDL_HAPTIC_SPRING: Effect based on axes position.
601-
/// - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
602-
/// - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
603-
/// - SDL_HAPTIC_FRICTION: Effect based on axes movement.
600+
/// - [`SDL_HAPTIC_SPRING`]: Effect based on axes position.
601+
/// - [`SDL_HAPTIC_DAMPER`]: Effect based on axes velocity.
602+
/// - [`SDL_HAPTIC_INERTIA`]: Effect based on axes acceleration.
603+
/// - [`SDL_HAPTIC_FRICTION`]: Effect based on axes movement.
604604
///
605605
/// Direction is handled by condition internals instead of a direction member.
606606
/// The condition effect specific members have three parameters. The first
@@ -1234,16 +1234,16 @@ extern "C" {
12341234
/// Run the haptic effect on its associated haptic device.
12351235
///
12361236
/// To repeat the effect over and over indefinitely, set `iterations` to
1237-
/// `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make
1237+
/// [`SDL_HAPTIC_INFINITY`]. (Repeats the envelope - attack and fade.) To make
12381238
/// one instance of the effect last indefinitely (so the effect does not fade),
1239-
/// set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
1239+
/// set the effect's `length` in its structure/union to [`SDL_HAPTIC_INFINITY`]
12401240
/// instead.
12411241
///
12421242
/// ### Arguments
12431243
/// - `haptic`: the [`SDL_Haptic`] device to run the effect on.
12441244
/// - `effect`: the ID of the haptic effect to run.
12451245
/// - `iterations`: the number of iterations to run the effect; use
1246-
/// `SDL_HAPTIC_INFINITY` to repeat forever.
1246+
/// [`SDL_HAPTIC_INFINITY`] to repeat forever.
12471247
/// ### Return value
12481248
/// Returns true on success or false on failure; call [`SDL_GetError()`] for more
12491249
/// information.
@@ -1331,8 +1331,8 @@ extern "C" {
13311331
/// Device must support the [`SDL_HAPTIC_GAIN`] feature.
13321332
///
13331333
/// The user may specify the maximum gain by setting the environment variable
1334-
/// `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to
1335-
/// [`SDL_SetHapticGain()`] will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
1334+
/// [`SDL_HAPTIC_GAIN_MAX`] which should be between 0 and 100. All calls to
1335+
/// [`SDL_SetHapticGain()`] will scale linearly using [`SDL_HAPTIC_GAIN_MAX`] as the
13361336
/// maximum.
13371337
///
13381338
/// ### Arguments
@@ -1383,7 +1383,7 @@ extern "C" {
13831383
extern "C" {
13841384
/// Pause a haptic device.
13851385
///
1386-
/// Device must support the `SDL_HAPTIC_PAUSE` feature. Call [`SDL_ResumeHaptic()`]
1386+
/// Device must support the [`SDL_HAPTIC_PAUSE`] feature. Call [`SDL_ResumeHaptic()`]
13871387
/// to resume playback.
13881388
///
13891389
/// Do not modify the effects nor add new ones while the device is paused. That

0 commit comments

Comments
 (0)