[api-extractor] Functions and Methods doesn't get their params

[MartynasZilinskas]

I started writing my own docs generating implementation and encountered some issues with api-extractor module.

Functions doesn't get its parameters because object is undefined. Source code: here and here

Example:

/**
 * Sum summary
 * @public
 * @returns Return summary.
 */
export function Sum(a: number, b: number): number {
    return a + b;
}

JSON output:

{
    "Sum": {
        "kind": "function",
        "returnValue": {
            "type": "number",
            "description": [{
                "kind": "textDocElement",
                "value": "Return summary."
            }]
        },
        "parameters": {},
        "deprecatedMessage": [],
        "summary": [{
            "kind": "textDocElement",
            "value": "Sum summary"
        }],
        "remarks": [],
        "isBeta": false
    }
}

I fixed quickly with this:

const parameters: { [key: string]: IParam } = {};

for (const param of apiFunction.params) {
    // FIXME: any
    parameters[param.name] = {} as any;

    this.visitApiParam(param, parameters[param.name]);
}

[octogonz]

This is a bug. Do you want me to create a PR to fix it? Or do you want to create the PR?

I started writing my own docs generating implementation and encountered some issues with api-extractor module.

Is your implementation open source? Our internal documentation pipeline is unfortunately very complicated (due to requirements of the docs.microsoft.com system), so it would be really useful to have a "reference implementation" that transforms the API Extractor JSON into simple HTML or Markdown pages. If you are coding something like this, it would be awesome if we could include it as part of the the api-extractor package.

I started writing something like this a couple weeks ago, and it revealed a bunch of little bugs and oversights in the JSON file that we had overlooked because our production pipeline has so many steps.

[MartynasZilinskas]

This is a bug. Do you want me to create a PR to fix it? Or do you want to create the PR?

If you can, it would be better you make the changes. I am not really that familiar with this code our how exactly is done. Here are current changes I made to ApiJsonGenerator.

Is your implementation open source?

Yes, it's in dev branch. Unfortunately it's a spaghetti code. First version of this package I am making for typescript projects so we don't need to write API docs by hand.

Looked at ApiJsonGenerator and ApiFileGenerator files, I was thinking about creating something similar, like ApiMarkdownGenerator.

[octogonz]

You will have a much easier time if you go JSON --> markdown instead of ApiItem tree --> markdown.

Here is a prototype branch that I was working on, which goes from JSON --> YAML (with each YAML file roughly corresponding to a page on an API documentation web site). The main loop is in ApiYamlWriter.ts. Because JSON is so easy to consume, the whole thing is only a couple hundred lines of code.

If you have a general spec for what you want your files to look like, this prototype would be pretty easy to repurpose to produce Markdown instead of YAML, particularly if we could use a proper library (markdown-creator?) instead of string manipulations to create the output. (Markdown has a very complex grammar, so we found that it's difficult to emit strings that don't accidentally get interpreted as formatting styles. Is that asterisk an asterisk, or is it part of a boldfaced region? Ooops, why did those spaces get interpreted as a callout block?)

My aim here would be to maintain a concise code sample that people can hack up and customize for their own documentation needs. (This is probably easier than providing a fancy templating system, which will never be customizable enough.) It would also give me a cheap way to validate new documentation scenarios, without waiting for our own big pipeline to support them.

Lemme know if you'd want to collaborate on something like that.

[MartynasZilinskas]

You will have a much easier time if you go JSON --> markdown instead of ApiItem tree --> markdown.

That's true. But in some cases I found that current JSON has not sufficient data to generate something like this:

Example Markdown

---

SetBar

Summary of SetBar method.

public SetBar(bar: Bar): void;

Parameters

• bar: Bar

Returns

void

---

Without modifying ApiJsonGenerator as far as I could go:

SetBar(bar: Bar): void

Access modifier (public, private, protected) is missing from current version of API JSON. Quick fix was, adding an additional property declarationLine and I got wanted results.

    // visitApiMethod method
    // ...
    declarationLine: apiFunction.getDeclarationLine(),

public SetBar(bar: Bar): void;

There are more places that would benefit from this property, like ApiProperty etc.

if we could use a proper library (markdown-creator?)

json2md was the first markdown library I came across. Looking at this library markdown-creator, it's exactly what I wanted from markdown generator.

Lemme know if you'd want to collaborate on something like that.

Yeah, sure. api-extractor still needs a little tweaks and bug fixes, so we can get useful data for generating markdown.

[octogonz]

Access modifier (public, private, protected) is missing from current version of API JSON.

Could you open a separate GitHub issue to track this (and any other limitations you encounter)? We are actively working on the documentation pipeline, including JSON schema improvements, and will prioritize this sort of issue. You can also feel free to create a pull request to fix any missing data issues in the JSON -- these are relatively easy fixes. :-)

Yeah, sure. api-extractor still needs a little tweaks and bug fixes, so we can get useful data for generating markdown.

Okay, maybe I can start by creating a small PR to add the basic skeleton of the Markdown generator, and then you could base your implementation on that, and give us suggestions? I don't really care what your Markdown output looks like, since we will treat it merely as a code sample (that we maintain and use for testing).

Looking at this library markdown-creator, it's exactly what I wanted from markdown generator.

I'm fine with that. FYI looking at the implementation, it is missing an escaping mechanism. For example, if you do this:

markdown.italic(' Here is my text');

Then you will get this (because of the space before H):

• Here is my text*

Or this:

markdown.italic('Avoid using an asterisk("*")');

Will print this (because the star is not escaped):

Avoid using an asterisk("")

This issue will probably be negligible for casual usage, but if you get serious about your documentation, you would want markdown-creator (or some other library) to handle these problems. You could file a bug for them.

Does that sound like a plan?

[MartynasZilinskas]

Could you open a separate GitHub issue to track this (and any other limitations you encounter)?

Alright.

I'm fine with that. FYI looking at the implementation, it is missing an escaping mechanism.

I will do a little research, what are other alternatives for markdown generation. We will see about that.

Does that sound like a plan?

Sounds like a plan 😄

[octogonz]

FYI I started work on this. Here's my PR branch if you want to follow along:

PR 322 Initial prototype of api-documenter tool

I'll update this issue when I've merged the first prototype.

[octogonz]

Hi @MartynasZilinskas - following up on this. The initial implementation is fairly close to being finished. I completed the main loop, and now just need to fill out all the different types of data. You can see an example of the current output on this web site:

https://microsoft.github.io/web-build-tools/api/

Let me know if you have any feedback about the layout.

[octogonz]

This should be fixed now.