Improving Solid Docs

[ghost]

As a UX designer and just a user It gets a bit difficult to read the docs to be honest. I believe the main reason for that is showing first the syntax and only then the description of a particular functionality .

In general and for the most cases, the first thing your readers want to know is what it is and only then how it's structured.

I have some suggestions in the example below. We could just move down the TypeScript definition and add a smaller heading like "Syntax". That's going to improve the readability a lot, not only for the new readers but also for the core team.

createSignal

This is the most basic reactive primitive used to track a single value that changes over time. The create function returns a get and set pair of functions to access and update the signal.

const [getValue, setValue] = createSignal(initialValue);

// read value
getValue();

// set value
setValue(nextValue);

// set value with a function setter
setValue((prev) => prev + next);

Remember to access signals under a tracking scope if you wish them to react to updates. Tracking scopes are functions that are passed to computations like createEffect or JSX expressions.

If you wish to store a function in a Signal you must use the function form:

 setValue(() => myFunction);

Syntax

export function createSignal<T>(
  value: T,
  options?: { name?: string; equals?: false | ((prev: T, next: T) => boolean) }
): [get: () => T, set: (v: T) => T];