Skip to content

Commit

Permalink
Clarify stdlib-docgen example
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
cheneym2 authored Nov 20, 2024
1 parent 7c41446 commit 958ca4c
Showing 1 changed file with 10 additions and 1 deletion.
11 changes: 10 additions & 1 deletion docs/stdlib-docgen.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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<float, Shape.dimensions+isArray> location, constexpr vector<int, Shape.planeDimensions> 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
Expand Down

0 comments on commit 958ca4c

Please sign in to comment.