diff --git a/arkoala-arkts/arkui/src/ArkCustomComponent.ts b/arkoala-arkts/arkui/src/ArkCustomComponent.ts index 0e93dbeeef0200449489d1bf3972ae6c6eeef0a5..803efe952d1311f54104d89a331846e4b205a070 100644 --- a/arkoala-arkts/arkui/src/ArkCustomComponent.ts +++ b/arkoala-arkts/arkui/src/ArkCustomComponent.ts @@ -30,7 +30,7 @@ import { /** * This is basically the CustomComponent, which doesn't extend CommonAttribute * - * @memo markup according to arkui-common/config/tsconfig.base.json + * memo markup according to arkui-common/config/tsconfig.base.json * * "render": { * "method": [ diff --git a/arkoala-arkts/arkui/src/handwritten/ArkPageTransition.ts b/arkoala-arkts/arkui/src/handwritten/ArkPageTransition.ts index afcb581080502659c5c2215ccf48700391908771..ea1ac2b7a8acfc0962a4923c49baadc8dbf793b7 100644 --- a/arkoala-arkts/arkui/src/handwritten/ArkPageTransition.ts +++ b/arkoala-arkts/arkui/src/handwritten/ArkPageTransition.ts @@ -28,9 +28,7 @@ import { } from "./ArkPageTransitionData" import { PageTransitionOptions } from "../generated" -/** - * @memo - */ +/** @memo */ function NotifyPageTransition(pageId: int32, style: ArkPageTransitionData, state: RouterTransitionVisibility) { const node = contextNode(PeerNodeType) // console.log("NotifyPageTransition: shall notify", "page", pageId, "state is", RouterTransitionVisibility[state]) @@ -52,9 +50,7 @@ function NotifyPageTransition(pageId: int32, style: ArkPageTransitionData, state }) } -/** - * @memo - */ +/** @memo */ export function ArkPageTransitionEnter( /** @memo */ style: ((attributes: ArkPageTransitionEnterComponent) => void) | undefined, @@ -70,9 +66,7 @@ export function ArkPageTransitionEnter( // } } -/** - * @memo - */ +/** @memo */ export function ArkPageTransitionExit( /** @memo */ style: ((attributes: ArkPageTransitionExitComponent) => void) | undefined, @@ -86,4 +80,4 @@ export function ArkPageTransitionExit( // if (state !== undefined && state.visibility == RouterTransitionVisibility.Hiding) { // NotifyPageTransition(state.pageId, receiver, RouterTransitionVisibility.Hiding) // } -} \ No newline at end of file +} diff --git a/arkoala/arkui-common/src/ArkState.ts b/arkoala/arkui-common/src/ArkState.ts index 1ac933e8191e0d04714174b50e0017ae0b9bed61..0e0193eb832f8459b4fac812f9216c0ede8380af 100644 --- a/arkoala/arkui-common/src/ArkState.ts +++ b/arkoala/arkui-common/src/ArkState.ts @@ -20,9 +20,9 @@ import { MutableState, __context, __id, mutableState, scheduleCallback } from "@ * @param name - a name of a context state * @param supplier - initial value supplier used on the state creation * @returns a named state specified in the current context - * @memo:intrinsic * @internal */ +/** @memo:intrinsic */ export function contextLocalStateOf(name: string, supplier: () => Value): MutableState { return __context().namedState(name, () => observableProxy(supplier())) } diff --git a/arkoala/arkui-common/src/typescript/Router.ts b/arkoala/arkui-common/src/typescript/Router.ts index 9b5a826abe03cbfd71cb8c29158177acac6894c1..a85cac8eb850238e7811ad20d98814b00c511af8 100644 --- a/arkoala/arkui-common/src/typescript/Router.ts +++ b/arkoala/arkui-common/src/typescript/Router.ts @@ -373,9 +373,7 @@ class RouterImpl implements Router { } } -/** - * @memo - */ +/** @memo */ export function Routed( /** @memo */ initial: () => void, @@ -411,24 +409,21 @@ export function Routed( * Get the reference to current context's router. Could be undefined, if not in the routed context. * * @returns the current router if defined - * - * @memo */ +/** @memo */ export function CurrentRouter(): Router | undefined { return contextLocal(CURRENT_ROUTER)?.value } -/** - * @memo - */ +/** @memo */ export function CurrentRouterTransitionState(): RouterTransitionState | undefined { return contextLocal(CURRENT_ROUTER_TRANSITION)?.value } /** * @internal - * @memo */ +/** @memo */ export function WithRouterTransitionState( transition: RouterTransitionState | undefined, /** @memo */ diff --git a/arkoala/arkui/src/ArkCustomComponent.ts b/arkoala/arkui/src/ArkCustomComponent.ts index 293a8b90c2a86b864163d163ce1ba31663b7c415..9de85bb6b977a327ad19a84bf6b08bb6143beff7 100644 --- a/arkoala/arkui/src/ArkCustomComponent.ts +++ b/arkoala/arkui/src/ArkCustomComponent.ts @@ -1,6 +1,6 @@ /** - * `CustomComponent` is not annotated with `@memo` whereas its real semantic assumes some of its methods - * are actually `@memo` methods. Calling those methods on `CustomComponent` type leads to loosing `@memo` + * `CustomComponent` is not annotated with `memo` whereas its real semantic assumes some of its methods + * are actually `memo` methods. Calling those methods on `CustomComponent` type leads to loosing `memo` * context. To avoid that the annotated `ArkCustomComponent` subclass should be used instead. */ export abstract class ArkCustomComponent extends CustomComponent { diff --git a/incremental/compiler-plugin/src/analysis-visitor.ts b/incremental/compiler-plugin/src/analysis-visitor.ts index 1c2a18898945b01b54ac3c4118c9a9fbaf8f90bd..7f26df8dff35fa8afa4cd53cfae24e3fed25e177 100644 --- a/incremental/compiler-plugin/src/analysis-visitor.ts +++ b/incremental/compiler-plugin/src/analysis-visitor.ts @@ -33,14 +33,22 @@ import { } from "./util" import { ImportExport } from './import-export'; +function parseCommentDetails(comment: string, annotation: RuntimeNames): boolean { + if (!comment.includes(annotation)) return false + if (comment != `/** ${annotation} */`) { + console.log(`Warning: The /** ${annotation} */ should be a single jsdoc comment.`) + return true + } + return true +} function parseComment(comment: string): FunctionKind { let kind = FunctionKind.REGULAR - if (comment.includes(RuntimeNames.ANNOTATION_INTRINSIC)) { + if (parseCommentDetails(comment, RuntimeNames.ANNOTATION_INTRINSIC)) { kind = FunctionKind.MEMO_INTRINSIC - } else if (comment.includes(RuntimeNames.ANNOTATION_ENTRY)) { + } else if (parseCommentDetails(comment, RuntimeNames.ANNOTATION_ENTRY)) { // Do nothing - } else if (comment.includes(RuntimeNames.ANNOTATION)) { + } else if (parseCommentDetails(comment, RuntimeNames.ANNOTATION)) { kind = FunctionKind.MEMO } return kind diff --git a/incremental/runtime/src/animation/memo.ts b/incremental/runtime/src/animation/memo.ts index d5a095e87895d6c60fffacd646dd0c24fae3a43b..06792a01685eb260fc5d1671a6bc3197653cbb26 100644 --- a/incremental/runtime/src/animation/memo.ts +++ b/incremental/runtime/src/animation/memo.ts @@ -28,8 +28,8 @@ import { AnimationSpec, TimeAnimation, animation, constAnimation, periodicAnimat * @param generator dirty function that produces values we interested in * * @returns value of generator function taken once in sampleRate ms - * @memo */ +/** @memo */ export function sampledValue(sampleRate: uint32, generator: (tick: int64) => V): V { return rememberAnimatedState((): TimeAnimation => periodicAnimation(sampleRate, generator), true).value } @@ -41,8 +41,8 @@ export function sampledValue(sampleRate: uint32, generator: (tick: int64) => * @param animation - supplier of the animation definition * @param startNow - if animation shall start immediately after creation * @returns animated state with the specified animation - * @memo */ +/** @memo */ export function rememberAnimatedState(animation: () => TimeAnimation, startNow: boolean = false): AnimatedState { return remember(() => animatedState(animation(), startNow)) } @@ -56,8 +56,8 @@ export function rememberAnimatedState(animation: () => TimeAnimation, star * @param to - a target value that corresponds to the 1 state * @param from - a initial value that corresponds to the 0 state * @returns animated state with the specified transition - * @memo */ +/** @memo */ export function rememberNumberTransition(on: boolean, duration: uint32, easing: EasingCurve = Easing.Linear, to: float64 = 1.0, from: float64 = 0.0): AnimatedState { return rememberTransition(on, duration, easing, NumberAnimationRange(from, to)) } @@ -73,8 +73,8 @@ export function rememberNumberTransition(on: boolean, duration: uint32, easing: * @param compute - value supplier to be computed when state animated from 0 to 1 * @param initial - initial state of the transition (false to 0, true to 1) * @returns animated state with the specified transition - * @memo */ +/** @memo */ export function rememberTransition(on: boolean, duration: uint32, easing: EasingCurve, compute: AnimationRange, initial: boolean = on): AnimatedState { const state = rememberAnimatedState((): TimeAnimation => transition(duration, easing, compute, initial ? 1 : 0), on) RunEffect(!on, (paused: boolean): void => { state.paused = paused }) @@ -88,8 +88,8 @@ export function rememberTransition(on: boolean, duration: uint32, easing: * @param initial - initial value * @param animationProvider - factory producing a new animation from the current value and the target one * @returns a mutable state that automatically animates the value as it changes - * @memo */ +/** @memo */ export function rememberMutableAnimatedState(initial: Value, animationProvider: ImplicitAnimationProvider): MutableAnimatedState { return remember(() => mutableAnimatedState(initial, animationProvider)) } @@ -101,8 +101,8 @@ export function rememberMutableAnimatedState(initial: Value, animationPro * @param animationSpec - the animation specification that does not depend on changed values * @returns a mutable state that automatically animates the number value as it changes * @see rememberMutableAnimatedState - * @memo */ +/** @memo */ export function rememberMutableAnimatedStateNumber(initial: float64, animationSpec: Partial): MutableAnimatedState { return remember(() => mutableAnimatedState(initial, (from: float64, to: float64) => from == to ? constAnimation(to) @@ -117,8 +117,8 @@ export function rememberMutableAnimatedStateNumber(initial: float64, animationSp * @param parameter - initial value for controlling parameter * @param animationProvider - factory producing a new animation when parameter changed * @returns state animator with the animation created for given parameter - * @memo */ +/** @memo */ export function rememberAnimator(parameter: P, animationProvider: ParametrizedAnimationProvider): StateAnimator { return remember(() => stateAnimator(parameter, animationProvider)) } diff --git a/incremental/runtime/src/memo/bind.ts b/incremental/runtime/src/memo/bind.ts index ad57a6a356164f2e3569ac294298551dd0eaf5b7..e41c183a4aa604e59b05a03cd010bf3dd7ab0b1e 100644 --- a/incremental/runtime/src/memo/bind.ts +++ b/incremental/runtime/src/memo/bind.ts @@ -33,8 +33,8 @@ export class MemoCallbackContext { * Do not use this dangerous API if you do not understand the incremental engine deeply. * @see call * @internal - * @memo */ + /** @memo */ static Make(): MemoCallbackContext { return new MemoCallbackContext(__context(), __id()) } diff --git a/incremental/runtime/src/memo/changeListener.ts b/incremental/runtime/src/memo/changeListener.ts index dd11508615302020a4af3804e33b2bfdd74b4574..b4fd4b1d35e4a3849f5cb47e023afee7db2a079b 100644 --- a/incremental/runtime/src/memo/changeListener.ts +++ b/incremental/runtime/src/memo/changeListener.ts @@ -23,8 +23,8 @@ import { __context, __id } from "../internals" * Unlike {@link RunEffect}, the specified function is not executed at the first pass during initialization. * @param value - a trackable value to listen changes * @param listener - a function to perform if the given value has changed - * @memo:intrinsic */ +/** @memo:intrinsic */ export function OnChange(value: Value, listener: (value: Value) => void) { watch(__context(), __id(), false, value, listener) } @@ -34,8 +34,8 @@ export function OnChange(value: Value, listener: (value: Value) => void) * Unlike {@link OnChange} this function is also executed from the first pass. * @param value - a value controlling if effect shall run * @param effect - a function to perform if the given value has changed or initialized - * @memo:intrinsic */ +/** @memo:intrinsic */ export function RunEffect(value: Value, effect: (value: Value) => void) { watch(__context(), __id(), true, value, effect) } diff --git a/incremental/runtime/src/memo/contextLocal.ts b/incremental/runtime/src/memo/contextLocal.ts index 98f883b2d6ed58ba08010b888b92adea6c498d98..756ed0ae2560ded078dd0065ec26ec441fad6be2 100644 --- a/incremental/runtime/src/memo/contextLocal.ts +++ b/incremental/runtime/src/memo/contextLocal.ts @@ -19,8 +19,8 @@ import { State } from "../states/State" /** * @param name - a name of a context state * @returns the named context state or `undefined` if it does not exist - * @memo:intrinsic */ +/** @memo:intrinsic */ export function contextLocal(name: string): State | undefined { return __context().stateBy(name) } @@ -29,8 +29,8 @@ export function contextLocal(name: string): State | undefined { * @param name - a name of a context state * @returns a value of a context state * @throws Error if a named context state does not exist - * @memo:intrinsic */ +/** @memo:intrinsic */ export function contextLocalValue(name: string): Value { return __context().valueBy(name) } @@ -43,8 +43,8 @@ export function contextLocalValue(name: string): Value { * @param name - a name of a context state * @param value - a value of a named state to share within the given content * @param content - a scope content in which a named state is available - * @memo:intrinsic */ +/** @memo:intrinsic */ export function contextLocalScope( name: string, value: Value, diff --git a/incremental/runtime/src/memo/entry.ts b/incremental/runtime/src/memo/entry.ts index 5dddaae7b431961de5467a3925f980b38c0790e0..77439bafc722a1e00662dffa28097d11852eec95 100644 --- a/incremental/runtime/src/memo/entry.ts +++ b/incremental/runtime/src/memo/entry.ts @@ -45,8 +45,8 @@ export function memoRoot( * This is where regular code can enter the memo realm. * This function allows to run a memo function in a non-memo context. * @internal - * @memo:entry */ +/** @memo:entry */ export function memoEntry( __memo_context: StateContext, __memo_id: KoalaCallsiteKey, @@ -60,8 +60,8 @@ export function memoEntry( * This is where regular code can enter the memo realm. * This function allows to run a memo function in a non-memo context. * @internal - * @memo:entry */ +/** @memo:entry */ export function memoEntry1( __memo_context: StateContext, __memo_id: KoalaCallsiteKey, @@ -76,8 +76,8 @@ export function memoEntry1( * This is where regular code can enter the memo realm. * This function allows to run a memo function in a non-memo context. * @internal - * @memo:entry */ +/** @memo:entry */ export function memoEntry2( __memo_context: StateContext, __memo_id: KoalaCallsiteKey, diff --git a/incremental/runtime/src/memo/node.ts b/incremental/runtime/src/memo/node.ts index b64991205d9c5fc0165c26d9c71c22ee06a55b26..1525be35e12c0741e8c95cc633a49e6c8889dde7 100644 --- a/incremental/runtime/src/memo/node.ts +++ b/incremental/runtime/src/memo/node.ts @@ -23,8 +23,8 @@ import { IncrementalNode } from "../tree/IncrementalNode" * @param update - the node updater is invoked right after the node constructor, * than it can be invoked again if the values of the used states have changed * @internal - * @memo:intrinsic */ +/** @memo:intrinsic */ export function NodeAttach( create: () => Node, /** @memo */ @@ -46,8 +46,8 @@ export function NodeAttach( * @returns current node * @throws Error with the given name if node kind is not expected * @internal - * @memo:intrinsic */ +/** @memo:intrinsic */ export function contextNode(kind: uint32 = 1, name?: string): T { const node = __context().node if (node?.isKind(kind) == true) return node as T @@ -67,9 +67,7 @@ export class DataNode extends IncrementalNode { super(kind) } - /** - * @memo:intrinsic - */ + /** @memo:intrinsic */ static attach( kind: uint32, data: Data, diff --git a/incremental/runtime/src/memo/remember.ts b/incremental/runtime/src/memo/remember.ts index 090c1a8b98e921b68755b5f7688c5ba3a0b7f437..97bf91867ccf8ba2a78d14cd65f610cc436c8d1e 100644 --- a/incremental/runtime/src/memo/remember.ts +++ b/incremental/runtime/src/memo/remember.ts @@ -21,15 +21,15 @@ import { ArrayState, ControlledScope, MutableState } from "../states/State" /** * It calculates the value of the given lambda and caches its result. * In contrast to the `remember` function, the given lambda can be recalculated - * if it uses values of states (including parameters of @memo-functions). + * if it uses values of states (including parameters of memo-functions). * If the given lambda does not use any state, it will be calculated only once. * * @param compute - a function to compute cacheable result * @returns the last calculated value * @see remember * @experimental - * @memo:intrinsic */ +/** @memo:intrinsic */ export function memo(compute: () => Value): Value { const scope = __context().scope(__id()) return scope.unchanged ? scope.cached : scope.recache(compute()) @@ -46,8 +46,8 @@ export function memo(compute: () => Value): Value { * @see once * @see remember * @internal - * @memo:intrinsic */ +/** @memo:intrinsic */ export function memoLifecycle(onAttach: () => void, onDetach: () => void): void { const scope = __context().scope(__id(), 0, undefined, undefined, (_: undefined) => onDetach(), true) // do not recalculate if used states were updated if (scope.unchanged) { @@ -64,8 +64,8 @@ export function memoLifecycle(onAttach: () => void, onDetach: () => void): void * Therefore, it is recommended to use {@link scheduleCallback}. * @param callback - a function to run on attach * @see remember - * @memo:intrinsic */ +/** @memo:intrinsic */ export function once(callback: () => void): void { const scope = __context().scope(__id(), 0, undefined, undefined, undefined, true) // do not recalculate if used states were updated if (scope.unchanged) { @@ -79,13 +79,13 @@ export function once(callback: () => void): void { /** * It calculates the value of the given lambda and caches its result. * In contrast to the `memo` function, the given lambda is calculated only once - * even if it uses values of states (including parameters of @memo-functions). + * even if it uses values of states (including parameters of memo-functions). * * @param compute - a function to compute cacheable result * @returns the last calculated value * @see memo - * @memo:intrinsic */ +/** @memo:intrinsic */ export function remember(compute: () => Value): Value { const scope = __context().scope(__id(), 0, undefined, undefined, undefined, true) // do not recalculate if used states were updated return scope.unchanged ? scope.cached : scope.recache(compute()) @@ -99,8 +99,8 @@ export function remember(compute: () => Value): Value { * @param cleanup - a function to clean up computed result on dispose * @returns the last calculated value * @see remember - * @memo:intrinsic */ +/** @memo:intrinsic */ export function rememberDisposable(compute: () => Value, cleanup: (value: Value | undefined) => void): Value { const scope = __context().scope(__id(), 0, undefined, undefined, cleanup, true) // do not recalculate if used states were updated return scope.unchanged ? scope.cached : scope.recache(compute()) @@ -115,8 +115,8 @@ export function rememberDisposable(compute: () => Value, cleanup: (value: * * @param initial - initial value supplier used on the state creation * @returns a state remembered for the current code position - * @memo:intrinsic */ +/** @memo:intrinsic */ export function rememberMutableState(initial: (() => Value) | Value): MutableState { const scope = __context().scope>(__id(), 0, undefined, undefined, undefined, true) // do not recalculate if used states were updated return scope.unchanged ? scope.cached : scope.recache(__context() @@ -132,8 +132,8 @@ export function rememberMutableState(initial: (() => Value) | Value): Mut * and if changed - all dependent memo functions recache automatically. * @param initial - initial array supplier used on the state creation * @returns an array state remembered for the current code position - * @memo:intrinsic */ +/** @memo:intrinsic */ export function rememberArrayState(initial?: () => ReadonlyArray): ArrayState { const scope = __context().scope>(__id(), 0, undefined, undefined, undefined, true) // do not recalculate if used states were updated return scope.unchanged ? scope.cached : scope.recache(__context().arrayState(initial?.())) @@ -163,8 +163,8 @@ function applyPromiseToState(promise: Promise, state: MutableState * @param compute function returning promise to compute the state * @param initial value stored to the state * @param onError callback called if promise was rejected - * @memo */ +/** @memo */ export function rememberMutableAsyncState(compute: () => Promise, initial?: Value, onError?: (error: Error) => void): MutableState { const result = rememberMutableState(initial) once(() => { applyPromiseToState(compute(), result, onError) }) @@ -180,8 +180,8 @@ export function rememberMutableAsyncState(compute: () => Promise( key: Key, /** @skip:memo */ @@ -204,8 +204,8 @@ export function rememberComputableState( * @param compute function returning promise to compute the state * @param initial value stored to the state * @param onError callback called if promise was rejected - * @memo */ +/** @memo */ export function rememberComputableValue( key: Key, /** @skip:memo */ @@ -219,8 +219,8 @@ export function rememberComputableValue( /** * @param invalidate - callback that will be notified when any state is modified within the scope * @return a user-controlled scope which can be used outside of the incremental update - * @memo:intrinsic */ +/** @memo:intrinsic */ export function rememberControlledScope(invalidate: () => void): ControlledScope { return __context().controlledScope(__id(), invalidate) } diff --git a/incremental/runtime/src/memo/repeat.ts b/incremental/runtime/src/memo/repeat.ts index 0063330a668a35b7cf995ee398b521f49962e338..150595d369d835479efcec112335bfc0ece0e78c 100644 --- a/incremental/runtime/src/memo/repeat.ts +++ b/incremental/runtime/src/memo/repeat.ts @@ -28,9 +28,8 @@ import { memoEntry1, memoEntry2 } from "./entry" * @see RepeatWithKey * @see RepeatByArray * @see Items - * - * @memo */ +/** @memo */ export function Repeat( count: int32, /** @memo */ @@ -53,9 +52,8 @@ export function Repeat( * @param action an action to repeat * * @see Repeat - * - * @memo */ +/** @memo */ export function RepeatWithKey( count: int32, key: (index: int32) => KoalaCallsiteKey, @@ -76,9 +74,8 @@ export function RepeatWithKey( * @param action an action to repeat * * @see RepeatWithKey - * - * @memo */ +/** @memo */ export function RepeatByArray( array: ReadonlyArray, key: (element: T, index: int32) => KoalaCallsiteKey, @@ -100,9 +97,8 @@ export function RepeatByArray( * @param element - the function to provide an element by its index * @param key - the function to provide a key for the element * @param action - the memo function to be invoked for every element - * - * @memo */ +/** @memo */ export function RepeatRange( start: int32, end: int32,