No documentation for the on function in Website

[Pingear]

There is no documentation for on() function on the site. https://ngrx.io/api/store/On Earlier issue for this topic was opened - #2487, but Tim @timdeschryver closed it for some reason, although the link he provided also does not work)

[timdeschryver]

Thanks for filing this @Pingear , at the time I thought the shared link in the referenced issue was showing the docs.

[ngfelixl]

Is someone working on it? Otherwise I would be happy to support. 😃

[timdeschryver]

@ngfelixl that would be great 👍

[ngfelixl]

@timdeschryver I think the problem occurs during the dgeni ./tools/transforms/angular.io-package script. The problem is that there is an On structure and an on function. So it tries to create an On.json in the ./src/generated/docs/api/store/ folder and then a on.json in the same folder, which is failing. The folder only contains the On.json after running the script.

The console output when running yarn docs:

$ yarn docs
yarn run v1.22.4
$ yarn generate-stackblitz && yarn generate-zips
$ node ./tools/stackblitz-builder/generateStackblitz
$ node ./tools/example-zipper/generateZips
$ yarn docs-only
$ dgeni ./tools/transforms/angular.io-package
info:    running processor: readFilesProcessor
info:    running processor: extractJSDocCommentsProcessor
info:    running processor: collectExamples
info:    running processor: readTypeScriptModules
info:    running processor: linkInheritedDocs
info:    running processor: parseTagsProcessor
info:    running processor: extractTagsProcessor
warn:    Invalid tags found - doc "store/on" (function)  - from file "/Users/felixlemke/Documents/development/platform/modules/store/src/reducer_creator.ts" - starting at line 12, ending at line 36
Line: 20: @example on(AuthApiActions.lo...

What do you think would be the best procedure here?

[timdeschryver]

@ngfelixl good catch. I do think there are two problems here:

1. the warning Invalid tags found is because we're using a @example tag in the JSDocs. This should be renamed to @usageNotes (and the code block can be surrounded with the ts code block e.g. ```ts. (Fyi, inside entity-services-base (from @ngrx/data) there's also an invalid @example tag.)
2. By doing (1) the docs are there, but the on docs are overwriting the On docs because they share the same name. To fix this we should rename one of the two. I'm not sure if we should do this, so I'm summoning @brandonroberts and @alex-okrushko . Perhaps that we can rename the On interface to OnResult or OnReducers? I'm not sure if this is worth it, since this is a part of our public API and thus a breaking change if we would rename it. (I also tried to hide On by using the @internal JSDoc tag, but with no result...)