From 958ca4c4f3200276419c5931dc5231750d618f49 Mon Sep 17 00:00:00 2001 From: cheneym2 Date: Wed, 20 Nov 2024 10:59:03 -0500 Subject: [PATCH] Clarify stdlib-docgen example Add a clarification on the example provided regarding documenting only the first overload. Though the example follows immediately after an existing explanation that only the first overload is present, and that _all_ parameters must be documented there, an extra sentence and the shell of a second overload help drive home the point. --- docs/stdlib-docgen.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/stdlib-docgen.md b/docs/stdlib-docgen.md index 1ccd430527..ceaffd76ea 100644 --- a/docs/stdlib-docgen.md +++ b/docs/stdlib-docgen.md @@ -54,7 +54,7 @@ You can use markdown syntax in any part of the comment. For overloaded functions, only document the first overload. List all parameters from all overloads in the same comment block for the first overload. Documentation on the remaining overloads will be ignored by the tool. If an overloaded decl has differing documentation on different overload candidates, the `slangc` tool will emit a warning. -The following code is an example of how `_Texture.Sample` is documented. +The following code is an example of how `_Texture.Sample` is documented. Notice that only the first overload is documented, and it also includes documentation for parameters which are only present in subsequent overloads, such as `offset`. ```csharp /// Samples the texture at the given location. @@ -84,6 +84,15 @@ The following code is an example of how `_Texture.Sample` is documented. { ... } + + [__readNone] + [ForceInline] + [require(cpp_glsl_hlsl_metal_spirv_wgsl, texture_sm_4_0_fragment)] + T Sample(vector location, constexpr vector offset) + { + ... + } + ``` Note that unlike doxygen, the directives marks the start of a new section, and applies to all following paragraphs. You don't need to repetitively mark new paragraphs