From 3212f74db68a526754ce107f1d3e1da0809c4678 Mon Sep 17 00:00:00 2001 From: Marvin <33938500+marvin-j97@users.noreply.github.com> Date: Fri, 23 Feb 2024 00:40:17 +0100 Subject: [PATCH] Adjust some JSDocs (#2081) * docs: adjust jsdocs * Create real-deers-end.md --------- Co-authored-by: Ryan Carniato --- .changeset/real-deers-end.md | 5 +++++ packages/solid/src/reactive/array.ts | 5 +++-- packages/solid/src/reactive/observable.ts | 2 +- packages/solid/src/reactive/signal.ts | 10 +++++----- packages/solid/src/render/Suspense.ts | 4 ++-- packages/solid/src/render/flow.ts | 8 ++++---- packages/solid/store/src/store.ts | 2 +- packages/solid/web/src/index.ts | 5 +++-- 8 files changed, 24 insertions(+), 17 deletions(-) create mode 100644 .changeset/real-deers-end.md diff --git a/.changeset/real-deers-end.md b/.changeset/real-deers-end.md new file mode 100644 index 000000000..d6820ca94 --- /dev/null +++ b/.changeset/real-deers-end.md @@ -0,0 +1,5 @@ +--- +"solid-js": patch +--- + +Adjust some JSDocs diff --git a/packages/solid/src/reactive/array.ts b/packages/solid/src/reactive/array.ts index fe64fa93c..91af3758a 100644 --- a/packages/solid/src/reactive/array.ts +++ b/packages/solid/src/reactive/array.ts @@ -37,8 +37,9 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ + /** - * reactively transforms an array with a callback function - underlying helper for the `` control flow + * Reactively transforms an array with a callback function - underlying helper for the `` control flow * * similar to `Array.prototype.map`, but gets the index as accessor, transforms only values that changed and returns an accessor and reactively tracks changes to the list. * @@ -175,7 +176,7 @@ export function mapArray( } /** - * reactively maps arrays by index instead of value - underlying helper for the `` control flow + * Reactively maps arrays by index instead of value - underlying helper for the `` control flow * * similar to `Array.prototype.map`, but gets the value as an accessor, transforms only changed items of the original arrays anew and returns an accessor. * diff --git a/packages/solid/src/reactive/observable.ts b/packages/solid/src/reactive/observable.ts index 3cc533e73..921c51034 100644 --- a/packages/solid/src/reactive/observable.ts +++ b/packages/solid/src/reactive/observable.ts @@ -34,7 +34,7 @@ export type ObservableObserver = complete?: (v: boolean) => void; }; /** - * creates a simple observable from a signal's accessor to be used with the `from` operator of observable libraries like e.g. rxjs + * Creates a simple observable from a signal's accessor to be used with the `from` operator of observable libraries like e.g. rxjs * ```typescript * import { from } from "rxjs"; * const [s, set] = createSignal(0); diff --git a/packages/solid/src/reactive/signal.ts b/packages/solid/src/reactive/signal.ts index 6abc5018e..fea41b96b 100644 --- a/packages/solid/src/reactive/signal.ts +++ b/packages/solid/src/reactive/signal.ts @@ -902,7 +902,7 @@ export interface OnOptions { } /** - * on - make dependencies of a computation explicit + * Makes dependencies of a computation explicit * ```typescript * export function on( * deps: Accessor | AccessorArray, @@ -962,7 +962,7 @@ export function on( } /** - * onMount - run an effect only after initial render on mount + * Runs an effect only after initial render on mount * @param fn an effect that should run only once on mount * * @description https://www.solidjs.com/docs/latest/api#onmount @@ -972,7 +972,7 @@ export function onMount(fn: () => void) { } /** - * onCleanup - run an effect once before the reactive scope is disposed + * Runs an effect once before the reactive scope is disposed * @param fn an effect that should run only once on cleanup * * @returns the same {@link fn} function that was passed in @@ -989,7 +989,7 @@ export function onCleanup any>(fn: T): T { } /** - * catchError - run an effect whenever an error is thrown within the context of the child scopes + * Runs an effect whenever an error is thrown within the context of the child scopes * @param fn boundary for the error * @param handler an error handler that receives the error * @@ -1176,7 +1176,7 @@ export function createContext( } /** - * use a context to receive a scoped state from a parent's Context.Provider + * Uses a context to receive a scoped state from a parent's Context.Provider * * @param context Context object made by `createContext` * @returns the current or `defaultValue`, if present diff --git a/packages/solid/src/render/Suspense.ts b/packages/solid/src/render/Suspense.ts index f2dce0aa8..056ecb4fc 100644 --- a/packages/solid/src/render/Suspense.ts +++ b/packages/solid/src/render/Suspense.ts @@ -28,7 +28,7 @@ const suspenseListEquals = (a: SuspenseListRegisteredState, b: SuspenseListRegis const SuspenseListContext = createContext(); /** - * **[experimental]** controls the order in which suspended content is rendered + * **[experimental]** Controls the order in which suspended content is rendered * * @description https://www.solidjs.com/docs/latest/api#suspenselist-experimental */ @@ -110,7 +110,7 @@ export function SuspenseList(props: { } /** - * tracks all resources inside a component and renders a fallback until they are all resolved + * Tracks all resources inside a component and renders a fallback until they are all resolved * ```typescript * const AsyncComponent = lazy(() => import('./component')); * diff --git a/packages/solid/src/render/flow.ts b/packages/solid/src/render/flow.ts index 1b6f329b6..f2049c2bd 100644 --- a/packages/solid/src/render/flow.ts +++ b/packages/solid/src/render/flow.ts @@ -19,7 +19,7 @@ const narrowedError = (name: string) => : `Stale read from <${name}>.`; /** - * creates a list elements from a list + * Creates a list elements from a list * * it receives a map function as its child that receives a list element and an accessor with the index and returns a JSX-Element; if the list is empty, an optional fallback is returned: * ```typescript @@ -144,7 +144,7 @@ export function Show(props: { type EvalConditions = readonly [number, unknown?, MatchProps?]; /** - * switches between content based on mutually exclusive conditions + * Switches between content based on mutually exclusive conditions * ```typescript * }> * @@ -208,7 +208,7 @@ export type MatchProps = { children: JSX.Element | ((item: NonNullable | Accessor>) => JSX.Element); }; /** - * selects a content based on condition when inside a `` control flow + * Selects a content based on condition when inside a `` control flow * ```typescript * * @@ -238,7 +238,7 @@ export function resetErrorBoundaries() { Errors && [...Errors].forEach(fn => fn()); } /** - * catches uncaught errors inside components and renders a fallback content + * Catches uncaught errors inside components and renders a fallback content * * Also supports a callback form that passes the error and a reset function: * ```typescript diff --git a/packages/solid/store/src/store.ts b/packages/solid/store/src/store.ts index 13e5262dd..ab081ab62 100644 --- a/packages/solid/store/src/store.ts +++ b/packages/solid/store/src/store.ts @@ -491,7 +491,7 @@ export interface SetStoreFunction { } /** - * creates a reactive store that can be read through a proxy object and written with a setter function + * Creates a reactive store that can be read through a proxy object and written with a setter function * * @description https://www.solidjs.com/docs/latest/api#createstore */ diff --git a/packages/solid/web/src/index.ts b/packages/solid/web/src/index.ts index 04be5059c..bdd33d23e 100644 --- a/packages/solid/web/src/index.ts +++ b/packages/solid/web/src/index.ts @@ -47,7 +47,7 @@ export const hydrate: typeof hydrateCore = (...args) => { }; /** - * renders components somewhere else in the DOM + * Renders components somewhere else in the DOM * * Useful for inserting modals and tooltips outside of an cropping layout. If no mount point is given, the portal is inserted in document.body; it is wrapped in a `
` unless the target is document.head or `isSVG` is true. setting `useShadow` to true places the element in a shadow root to isolate styles. * @@ -113,8 +113,9 @@ export type DynamicProps> = { } & { component: T | undefined; }; + /** - * renders an arbitrary custom or native component and passes the other props + * Renders an arbitrary custom or native component and passes the other props * ```typescript * * ```