-
Notifications
You must be signed in to change notification settings - Fork 134
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC: Syntax for @example tag #20
Comments
In the case of DocFX, we definitely want to move away from inlined samples and into includes (see: file inclusion). As such, I like the proposal of having the tag be Markdown-ready. |
I always thought If there will be some kind of /**
* Adds two numbers together.
* @example
* Here's a simple example:
* {@include example1.ts}
* @example
* Here's an example with negative numbers:
* {@include example2.ts}
*/
export function add(x: number, y: number): number {
} This way, it's easy to include several code snippets within the same example and reuse example codes at several places. |
@pgonzal I'm not sure I understand your question but the code you have looks good to me. My main question is where should the example tag block end? Would it be on an empty line or the next block annotation? |
@aciccarello I guess your question will be answered here: #12 |
/* @example
/* > plusOne(3)
/* 4 One could create a tool that executes I haven't given much thought to the different scenarios and why this might or might not make sense in the context of JS/TS. Maybe we need a new tag. /* @example addOne(3)
/* @expect 4 Sorry for the brainstorming. |
@kiliancs That seems to me like something that should stay in the example code and not be handled by the documentation tool. Interesting idea though. /**
* @example
* Adding one adds one
* ```typescript
* import plusOne from 'plus-one';
* import expect from 'test-lib';
*
* const actual = plusOne(3);
* expect(actual).toEqual(4);
* ```
*/
export function plusOne(input: number) {
return input + 1;
} |
@pgonzal I can have for Angular documentation tool https://github.com/compodoc/compodoc this kind of @example usage which use TypeScript decorator.
|
Recently I've been starting to question the need for a dedicated |
I suppose depends on your documentation template. Right now API Extractor renders @dend Does DocFX treat example sections differently from other sections? |
The TSDoc Playground does not implement API Extractor is a separate project that incorporates TSDoc, but is not itself part of the TSDoc standard. API Extractor supports the |
BTW if |
I prefer the markdown tactic as an example might not necessarily be all TypeScript. On another note, think it would be helpful to support a name/title for examples. Maybe in Example (where text on the same line is the name of the example, and code besides TypeScript is included): /**
* Parses a JSON file.
* @param path - Full path to the file.
* @returns An object containing the JSON data.
* @example Parsing a basic JSON file
* ##Contents of `file.json`:
* ```json
* {
* exampleItem: "text"
* }
* ```
*
* ##Usage:
* ```ts
* const result = parseFile("file.json");
* ```
*
* ##Result:
* ```ts
* {
* exampleItem: 'text',
* }
* ```
*/ |
That's a good suggestion. Currently API Documenter simply generates names like
There's already some precedent, where the /**
* Retrieves metadata about a book from the catalog.
*
* @param isbnCode - the ISBN number for the book
* @returns the retrieved book object
*
* @throws {@link IsbnSyntaxError}
* This exception is thrown if the input is not a valid ISBN number.
*
* @throws {@link book-lib#BookNotFoundError}
* Thrown if the ISBN number is valid, but no such book exists in the catalog.
*
* @public
*/
function fetchBookByIsbn(isbnCode: string): Book; So maybe a similar convention could be used for So it could be like this: /**
* Parses a JSON file.
*
* @param path - Full path to the file.
* @returns An object containing the JSON data.
*
* @example Parsing a basic JSON file
*
* # Contents of `file.json`
* ```json
* {
* "exampleItem": "text"
* }
* ```
*
* # Usage
* ```ts
* const result = parseFile("file.json");
* ```
*
* # Result
* ```ts
* {
* exampleItem: 'text',
* }
* ```
*/ ...and might get rendered like this:
|
The docs mention that inline text should be parsed as headings, but both the api and the playground treat them as normal paragraphs. Is this intentional or just un-implemented? |
Adding example title's also breaks whitespace rendering in VSCode which is a pretty big problem. I've been able to roll my own type extractor to compensate for the lack of support here (although I would have preferred to be able to just use Does VSCode use |
No, how I understand it, VS Code implements a proprietary analysis that isn't based on any spec. It's just a best attempt to render the kinds of We could try to improve that. However because TSDoc's goal is to provide a rigorous and unambiguous syntax, a better approach would be to create a VS Code extension specifically for TSDoc. Then we could perfectly parse TSDoc syntax and provide much better rendering. If someone's interested in contributing to a project like that, let us know. 🙏 In the past this idea was blocked because we were missing the CI infrastructure for publishing extensions to the VS Code marketplace, but Microsoft solved that recently for us as part of setting up the VS Code extension for Rush (another Rush Stack project). |
RFC: Core set of tags for TSDoc brought up the question of the
@example
tag that could be used to identify examples. I'm forking it into a separate issue since @c69 pointed out that the design is unclear.Can anyone find samples of its usage in existing documentation systems?
Since TSDoc will support Markdown, how would it interact with that? Maybe something like this?
How would an API reference web site leverage these directives?
@aciccarello
The text was updated successfully, but these errors were encountered: