[Content]: show#render-function rely on code comments to explain the tracked case

[mizulu]

📚 Subject area/topic

📋 Page(s) affected (or suggested, for new content)

Rendered:
https://docs.solidjs.com/reference/components/show#render-function

Source:
https://github.com/solidjs/solid-docs/blob/main/src/routes/reference/components/show.mdx?plain=1#L62-L83

The current docs explains/focus on the untrack case in the description, but rely on the code example
to show tracked/reactive.
to my understanding we do not want code examples ( or comments in code example )
to replace explanations / descriptions in the learning materials. ( as noted by @LadyBluenotes in another PR )

---

The PR was already merged and some comments were added after.
and it was requested that further discussion will be tracked in a new issue.

I have suggested to split the example and explain each case.

The tracked case the more common and desirable case. we should consider being explicit
on the correct usage as well as show how it may fail to be reactive like we already do.

another concern was regarding the outer/inner jsx in the comment

it was suggested to use a more generic term in the comment as to not increase mental overhead

{/* This will update because the returned JSX element creates a new tracking scope. */}

which will replace

but if we go with the split code example for each case
the comments are not even needed.as explanation will cover each case.

📋 Description of content that is out-of-date or incorrect

see full issue description above.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[mizulu]

Ref: #1163 Improve <Show> reference

[mizulu]

[LadyBluenotes]

I think this could be a worthwhile update to it. It's important to take into account, however, that we do have a section of the docs that talks about <Show> and we need to take into account that references should be used as a way to deliver facts. We want to avoid adding opinions or interpretations here so it may be worth evaluating whether this is something that could be helpful in the core docs vs the reference docs.

For context, we use the diataxis as our framework for writing docs - if you want to read more on references you can see it here.

I'm half wondering if this is something that may be beneficial to mention in the core section (eg. https://docs.solidjs.com/concepts/control-flow/conditional-rendering#show) rather than the reference one.

[mizulu]

we do have a section of the docs that talks about

from what I can see the https://docs.solidjs.com/concepts/control-flow/conditional-rendering#show
is currently focused on the high level concept / simplified use of conditional render with <Show>
(show some jsx or show fallback based on the boolean condition)

introducing more details about <Show> feature there may shift the focus off the topic it discusses
as show becomes more then just conditional rendered and fallback, it also starts to deal
with values passed to the render function.

I'm half wondering if this is something that may be beneficial to mention in the core section

I think the Reference for <Show> does covers the key functionality of the component.

• render function
  • tracked / untracked
  • argument accessor/value
• fallback
• keyed

and mostly inline with the diataxis::References guide you have linked
going with the direction of the suggestion in this issue, can improve that further.

perhaps <Show> might need a more extensive "learning resource" in core
to cover all the possible usages. but I personally find the reference almost "feature complete"
in respect to examples and feature coverage.