Adjust doc comments that misrender as CommonMark

core/c/libc/stdio.odin

@@ -38,7 +38,7 @@ when ODIN_OS == .Windows {
 
 	FILENAME_MAX :: 260
 
-	L_tmpnam     :: 15 // "\\" + 12 + NUL
+	L_tmpnam     :: 15 // `"\\" + 12 + NUL`
 
 	SEEK_SET     :: 0
 	SEEK_CUR     :: 1

core/math/big/prime.odin

@@ -833,9 +833,9 @@ internal_int_prime_strong_lucas_selfridge :: proc(a: ^Int, allocator := context.
 /*
 	Performs one Fermat test.
 
-	If "a" were prime then b**a == b (mod a) since the order of
-	the multiplicative sub-group would be phi(a) = a-1.  That means
-	it would be the same as b**(a mod (a-1)) == b**1 == b (mod a).
+	If "a" were prime then `b**a == b (mod a)` since the order of
+	the multiplicative sub-group would be `phi(a) = a-1`.  That means
+	it would be the same as `b**(a mod (a-1)) == b**1 == b (mod a)`.
 
 	Returns `true` if the congruence holds, or `false` otherwise.
 

core/math/big/private.odin

@@ -227,15 +227,15 @@ _private_int_mul_toom :: proc(dest, a, b: ^Int, allocator := context.allocator)
 }
 
 /*
-	product = |a| * |b| using Karatsuba Multiplication using three half size multiplications.
+	`product = |a| * |b|` using Karatsuba Multiplication using three half size multiplications.
 
-	Let `B` represent the radix [e.g. 2**_DIGIT_BITS] and let `n` represent
+	Let `B` represent the radix [e.g. `2**_DIGIT_BITS`] and let `n` represent
 	half of the number of digits in the min(a,b)
 
-	`a` = `a1` * `B`**`n` + `a0`
-	`b` = `b`1 * `B`**`n` + `b0`
+	`a = a1 * B**n + a0`
+	`b = b1 * B**n + b0`
 
-	Then, a * b => 1b1 * B**2n + ((a1 + a0)(b1 + b0) - (a0b0 + a1b1)) * B + a0b0
+	Then, `a * b => a1b1 * B**2n + ((a1 + a0)(b1 + b0) - (a0b0 + a1b1)) * B + a0b0`
 
 	Note that a1b1 and a0b0 are used twice and only need to be computed once.
 	So in total three half size (half # of digit) multiplications are performed,
@@ -248,8 +248,8 @@ _private_int_mul_toom :: proc(dest, a, b: ^Int, allocator := context.allocator)
 	Note also that the call to `internal_mul` can end up back in this function
 	if the a0, a1, b0, or b1 are above the threshold.
 
-	This is known as divide-and-conquer and leads to the famous O(N**lg(3)) or O(N**1.584)
-	work which is asymptopically lower than the standard O(N**2) that the
+	This is known as divide-and-conquer and leads to the famous `O(N**lg(3))` or `O(N**1.584)`
+	work which is asymptopically lower than the standard `O(N**2)` that the
 	baseline/comba methods use. Generally though, the overhead of this method doesn't pay off
 	until a certain size is reached, of around 80 used DIGITs.
 */

core/math/rand/distributions.odin

@@ -91,11 +91,11 @@ float32_exponential :: proc(lambda: f32, gen := context.random_generator) -> f32
 //
 // Required: alpha > 0 and beta > 0
 //
-//             math.pow(x, alpha-1) * math.exp(-x / beta)
-//   pdf(x) = --------------------------------------------
-//              math.gamma(alpha) * math.pow(beta, alpha)
+// 	          math.pow(x, alpha-1) * math.exp(-x / beta)
+// 	pdf(x) = --------------------------------------------
+// 	           math.gamma(alpha) * math.pow(beta, alpha)
 //
-// mean is alpha*beta, variance is math.pow(alpha*beta, 2)
+// mean is `alpha*beta`, variance is `math.pow(alpha*beta, 2)`
 @(require_results)
 float64_gamma :: proc(alpha, beta: f64, gen := context.random_generator) -> f64 {
 	if alpha <= 0 || beta <= 0 {
@@ -157,11 +157,11 @@ float64_gamma :: proc(alpha, beta: f64, gen := context.random_generator) -> f64
 //
 // Required: alpha > 0 and beta > 0
 //
-//             math.pow(x, alpha-1) * math.exp(-x / beta)
-//   pdf(x) = --------------------------------------------
-//              math.gamma(alpha) * math.pow(beta, alpha)
+// 	          math.pow(x, alpha-1) * math.exp(-x / beta)
+// 	pdf(x) = --------------------------------------------
+// 	           math.gamma(alpha) * math.pow(beta, alpha)
 //
-// mean is alpha*beta, variance is math.pow(alpha*beta, 2)
+// mean is `alpha*beta`, variance is `math.pow(alpha*beta, 2)`
 @(require_results)
 float32_gamma :: proc(alpha, beta: f32, gen := context.random_generator) -> f32 {
 	return f32(float64_gamma(f64(alpha), f64(beta), gen))

core/net/addr.odin

@@ -24,12 +24,12 @@ import "core:strings"
 
 /*
 	Expects an IPv4 address with no leading or trailing whitespace:
-	- a.b.c.d
-	- a.b.c.d:port
-	- [a.b.c.d]:port
+	- `a.b.c.d`
+	- `a.b.c.d:port`
+	- `[a.b.c.d]:port`
 
 	If the IP address is bracketed, the port must be present and valid (though it will be ignored):
-	- [a.b.c.d] will be treated as a parsing failure.
+	- `[a.b.c.d]` will be treated as a parsing failure.
 
 	The port, if present, is required to be a base 10 number in the range 0-65535, inclusive.
 

core/simd/x86/avx.odin

@@ -200,9 +200,7 @@ _mm256_div_pd :: #force_inline proc "c" (a, b: __m256d) -> __m256d {
 // - `0x02`: Round up, toward positive infinity.
 // - `0x03`: Truncate the values.
 //
-// For a complete list of options, check [the LLVM docs][llvm_docs].
-//
-// [llvm_docs]: https://github.com/llvm-mirror/clang/blob/dcd8d797b20291f1a6b3e0ddda085aa2bbb382a8/lib/Headers/avxintrin.h#L382
+// For a complete list of options, check [the LLVM docs](https://github.com/llvm-mirror/clang/blob/dcd8d797b20291f1a6b3e0ddda085aa2bbb382a8/lib/Headers/avxintrin.h#L382).
 //
 // [Intel's documentation](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_pd)
 @(require_results, enable_target_feature="avx")
@@ -234,9 +232,7 @@ _mm256_floor_pd :: #force_inline proc "c" (a: __m256d) -> __m256d {
 // - `0x02`: Round up, toward positive infinity.
 // - `0x03`: Truncate the values.
 //
-// For a complete list of options, check [the LLVM docs][llvm_docs].
-//
-// [llvm_docs]: https://github.com/llvm-mirror/clang/blob/dcd8d797b20291f1a6b3e0ddda085aa2bbb382a8/lib/Headers/avxintrin.h#L382
+// For a complete list of options, check [the LLVM docs](https://github.com/llvm-mirror/clang/blob/dcd8d797b20291f1a6b3e0ddda085aa2bbb382a8/lib/Headers/avxintrin.h#L382).
 //
 // [Intel's documentation](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_ps)
 @(require_results, enable_target_feature="avx")

core/strconv/strconv.odin

@@ -1642,7 +1642,7 @@ Writes a quoted string representation of the input string to a given byte slice
 - buf: The byte slice to which the quoted string will be written
 - str: The input string to be quoted
 
-!! ISSUE !! NOT EXPECTED -- "\"hello\"" was expected
+!! ISSUE !! NOT EXPECTED -- `"\"hello\""` was expected
 
 Example:
 

core/sys/windows/gdi32.odin

@@ -229,20 +229,20 @@ BS_DIBPATTERN8X8 :: 8
 BS_MONOPATTERN   :: 9
 
 /* Hatch Styles */
-HS_HORIZONTAL    :: 0       /* ----- */
-HS_VERTICAL      :: 1       /* ||||| */
-HS_FDIAGONAL     :: 2       /* \\\\\ */
-HS_BDIAGONAL     :: 3       /* ///// */
-HS_CROSS         :: 4       /* +++++ */
-HS_DIAGCROSS     :: 5       /* xxxxx */
+HS_HORIZONTAL    :: 0       /* `-----` */
+HS_VERTICAL      :: 1       /* `|||||` */
+HS_FDIAGONAL     :: 2       /* `\\\\\` */
+HS_BDIAGONAL     :: 3       /* `/////` */
+HS_CROSS         :: 4       /* `+++++` */
+HS_DIAGCROSS     :: 5       /* `xxxxx` */
 HS_API_MAX       :: 12
 
 /* Pen Styles */
 PS_SOLID         ::  0
-PS_DASH          ::  1      /* ------- */
-PS_DOT           ::  2      /* ....... */
-PS_DASHDOT       ::  3      /* _._._._ */
-PS_DASHDOTDOT    ::  4      /* _.._.._ */
+PS_DASH          ::  1      /* `-------` */
+PS_DOT           ::  2      /* `.......` */
+PS_DASHDOT       ::  3      /* `_._._._` */
+PS_DASHDOTDOT    ::  4      /* `_.._.._` */
 PS_NULL          ::  5
 PS_INSIDEFRAME   ::  6
 PS_USERSTYLE     ::  7

core/sys/windows/key_codes.odin

@@ -213,7 +213,7 @@ VK_OEM_3      :: 0xC0 // '`~' for US
 // 0xC1 - 0xDA : reserved
 
 VK_OEM_4 :: 0xDB // '[{' for US
-VK_OEM_5 :: 0xDC // '\|' for US
+VK_OEM_5 :: 0xDC // `'\|'` for US
 VK_OEM_6 :: 0xDD // ']}' for US
 VK_OEM_7 :: 0xDE // ''"' for US
 VK_OEM_8 :: 0xDF
@@ -222,7 +222,7 @@ VK_OEM_8 :: 0xDF
 
 // Various extended or enhanced keyboards
 VK_OEM_AX   :: 0xE1  //  'AX' key on Japanese AX kbd
-VK_OEM_102  :: 0xE2  //  "<>" or "\|" on RT 102-key kbd.
+VK_OEM_102  :: 0xE2  //  `"<>"` or `"\|"` on RT 102-key kbd.
 VK_ICO_HELP :: 0xE3  //  Help key on ICO
 VK_ICO_00   :: 0xE4  //  00 key on ICO
 

core/sys/windows/types.odin

@@ -2249,7 +2249,7 @@ SEE_MASK_WAITFORINPUTIDLE  :: 0x02000000
 SEE_MASK_FLAG_LOG_USAGE    :: 0x04000000
 
 // When SEE_MASK_FLAG_HINST_IS_SITE is specified SHELLEXECUTEINFO.hInstApp is used as an
-// _In_ parameter and specifies a IUnknown* to be used as a site pointer. The site pointer
+// `_In_` parameter and specifies a `IUnknown*` to be used as a site pointer. The site pointer
 // is used to provide services to shell execute, the handler binding process and the verb handlers
 // once they are invoked.
 SEE_MASK_FLAG_HINST_IS_SITE :: 0x08000000
@@ -4304,7 +4304,7 @@ SHCONTF_ENABLE_ASYNC          :: 0x8000
 SHCONTF_INCLUDESUPERHIDDEN    :: 0x10000
 
 SHACF_DEFAULT               :: 0x00000000  // Currently (SHACF_FILESYSTEM | SHACF_URLALL)
-SHACF_FILESYSTEM            :: 0x00000001  // This includes the File System as well as the rest of the shell (Desktop\My Computer\Control Panel\)
+SHACF_FILESYSTEM            :: 0x00000001  // This includes the File System as well as the rest of the shell (`Desktop\My Computer\Control Panel\`)
 SHACF_URLALL                :: (SHACF_URLHISTORY | SHACF_URLMRU)
 SHACF_URLHISTORY            :: 0x00000002  // URLs in the User's History
 SHACF_URLMRU                :: 0x00000004  // URLs in the User's Recently Used list.
@@ -5481,10 +5481,9 @@ CRYPT_DIGEST_BLOB   :: distinct CRYPTOAPI_BLOB
 CRYPT_DER_BLOB      :: distinct CRYPTOAPI_BLOB
 CRYPT_ATTR_BLOB     :: distinct CRYPTOAPI_BLOB
 
-//+-------------------------------------------------------------------------
 //  In a CRYPT_BIT_BLOB the last byte may contain 0-7 unused bits. Therefore, the
 //  overall bit length is cbData * 8 - cUnusedBits.
-//--------------------------------------------------------------------------
+//
 // certenrolls_begin -- CERT_CONTEXT
 CRYPT_BIT_BLOB :: struct {
 	cbData:      DWORD,
@@ -5492,12 +5491,10 @@ CRYPT_BIT_BLOB :: struct {
 	cUnusedBits: DWORD,
 }
 
-//+-------------------------------------------------------------------------
 //  Type used for any algorithm
 //
 //  Where the Parameters CRYPT_OBJID_BLOB is in its encoded representation. For most
 //  algorithm types, the Parameters CRYPT_OBJID_BLOB is NULL (Parameters.cbData = 0).
-//--------------------------------------------------------------------------
 CRYPT_ALGORITHM_IDENTIFIER :: struct {
 	pszObjId:   LPSTR,
 	Parameters: CRYPT_OBJID_BLOB,

vendor/glfw/bindings/types.odin

@@ -38,6 +38,7 @@ Allocator :: struct {
 }
 
 /*** Procedure type declarations ***/
+
 WindowIconifyProc      :: #type proc "c" (window: WindowHandle, iconified: c.int)
 WindowRefreshProc      :: #type proc "c" (window: WindowHandle)
 WindowFocusProc        :: #type proc "c" (window: WindowHandle, focused: c.int)

vendor/glfw/constants.odin

@@ -4,6 +4,7 @@ package glfw
 GLFW_SHARED :: #config(GLFW_SHARED, false)
 
 /*** Constants ***/
+
 /* Versions */
 VERSION_MAJOR    :: 3
 VERSION_MINOR    :: 4
@@ -38,7 +39,7 @@ KEY_UNKNOWN :: -1
 KEY_SPACE         :: 32
 KEY_APOSTROPHE    :: 39  /* ' */
 KEY_COMMA         :: 44  /* , */
-KEY_MINUS         :: 45  /* - */
+KEY_MINUS         :: 45  /* `-` */
 KEY_PERIOD        :: 46  /* . */
 KEY_SLASH         :: 47  /* / */
 KEY_SEMICOLON     :: 59  /* ; */

vendor/glfw/types.odin

@@ -15,6 +15,7 @@ GamepadState :: glfw.GamepadState
 Allocator :: glfw.Allocator
 
 /*** Procedure type declarations ***/
+
 WindowIconifyProc      :: glfw.WindowIconifyProc
 WindowRefreshProc      :: glfw.WindowRefreshProc
 WindowFocusProc        :: glfw.WindowFocusProc

vendor/stb/vorbis/stb_vorbis.odin

@@ -152,14 +152,14 @@ foreign lib {
 	// to avoid missing parts of a page header if they cross a datablock boundary,
 	// without writing state-machiney code to record a partial detection.
 	//
-	// The number of channels returned are stored in *channels (which can be
+	// The number of channels returned are stored in `*channels` (which can be
 	// NULL--it is always the same as the number of channels reported by
-	// get_info). *output will contain an array of float* buffers, one per
-	// channel. In other words, (*output)[0][0] contains the first sample from
-	// the first channel, and (*output)[1][0] contains the first sample from
+	// get_info). `*output` will contain an array of `float*` buffers, one per
+	// channel. In other words, `(*output)[0][0]` contains the first sample from
+	// the first channel, and `(*output)[1][0]` contains the first sample from
 	// the second channel.
 	//
-	// *output points into stb_vorbis's internal output buffer storage; these
+	// `*output` points into stb_vorbis's internal output buffer storage; these
 	// buffers are owned by stb_vorbis and application code should not free
 	// them or modify their contents. They are transient and will be overwritten
 	// once you ask for more data to get decoded, so be sure to grab any data
@@ -239,10 +239,10 @@ foreign lib {
 	}
 
 	// these functions seek in the Vorbis file to (approximately) 'sample_number'.
-	// after calling seek_frame(), the next call to get_frame_*() will include
+	// after calling seek_frame(), the next call to `get_frame_*()` will include
 	// the specified sample. after calling stb_vorbis_seek(), the next call to
-	// stb_vorbis_get_samples_* will start with the specified sample. If you
-	// do not need to seek to EXACTLY the target sample when using get_samples_*,
+	// `stb_vorbis_get_samples_*` will start with the specified sample. If you
+	// do not need to seek to EXACTLY the target sample when using `get_samples_*`,
 	// you can also use seek_frame().
 	seek_frame :: proc(f: ^vorbis, sample_number: c.uint) -> c.int ---
 	seek       :: proc(f: ^vorbis, sample_number: c.uint) -> c.int ---
@@ -255,13 +255,13 @@ foreign lib {
 	stream_length_in_seconds :: proc(f: ^vorbis) -> f32 ---
 
 	// decode the next frame and return the number of samples. the number of
-	// channels returned are stored in *channels (which can be NULL--it is always
-	// the same as the number of channels reported by get_info). *output will
-	// contain an array of float* buffers, one per channel. These outputs will
-	// be overwritten on the next call to stb_vorbis_get_frame_*.
+	// channels returned are stored in `*channels` (which can be NULL--it is always
+	// the same as the number of channels reported by get_info). `*output` will
+	// contain an array of `float*` buffers, one per channel. These outputs will
+	// be overwritten on the next call to `stb_vorbis_get_frame_*`.
 	//
-	// You generally should not intermix calls to stb_vorbis_get_frame_*()
-	// and stb_vorbis_get_samples_*(), since the latter calls the former.
+	// You generally should not intermix calls to `stb_vorbis_get_frame_*()`
+	// and `stb_vorbis_get_samples_*()`, since the latter calls the former.
 	get_frame_float :: proc(f: ^vorbis, channels: ^c.int, output: ^[^]^f32) -> c.int ---
 
 	// decode the next frame and return the number of *samples* per channel.

vendor/wgpu/wgpu_native_types.odin

@@ -228,9 +228,7 @@ SurfaceConfigurationExtras :: struct {
 	desiredMaximumFrameLatency: u32,
 }
 
-/**
-* Chained in `SurfaceDescriptor` to make a `Surface` wrapping a WinUI [[ SwapChainPanel ; https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.swapchainpanel ]].
-*/
+// Chained in `SurfaceDescriptor` to make a `Surface` wrapping a WinUI [[ SwapChainPanel ; https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.swapchainpanel ]].
 SurfaceSourceSwapChainPanel :: struct {
 	using chain: ChainedStruct,
     /**