Skip to content
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

[api-documenter] MarkdownDocumenter: Links to referenced types in type cells #1611

Closed
1 of 2 tasks
thorbenziemek opened this issue Oct 30, 2019 · 4 comments · Fixed by #1849
Closed
1 of 2 tasks

[api-documenter] MarkdownDocumenter: Links to referenced types in type cells #1611

thorbenziemek opened this issue Oct 30, 2019 · 4 comments · Fixed by #1849
Labels
effort: medium Needs a somewhat experienced developer enhancement The issue is asking for a new feature or design change help wanted If you're looking to contribute, this issue is a good place to start!

Comments

@thorbenziemek
Copy link

Is this a feature or a bug?

  • Feature
  • Bug

Please describe the actual behavior.
Types in generated Markdown documentation do not include links to type definitions automatically. For instance, in a class documentation, there is a column "Type" in the properties table, which in my case always only contains the plain name of the referenced type.

What is the expected behavior?
I would expect the mentioned type cells to include a link to the type definition, if applicable. From what I understand so far, this could be possible in the _createPropertyCell function (

private _createPropertyTypeCell(apiItem: ApiItem): DocTableCell {
). Maybe loop over the excerpt's tokens and create a link to the type from the canonicalReferences. However, this would require something like getLinkFilenameForDeclarationReference(canonicalReference). Is this possible to implement / any ideas on this?

@octogonz octogonz added effort: medium Needs a somewhat experienced developer enhancement The issue is asking for a new feature or design change help wanted If you're looking to contribute, this issue is a good place to start! labels Nov 4, 2019
@octogonz
Copy link
Collaborator

octogonz commented Nov 4, 2019

PR #1337 already implemented this for the DocFX target. We very much want to support it for Markdown as well, just haven't gotten around to it yet.

If you're interested in helping out, that would be awesome! (I'm reachable on Gitter if you have questions about the design.)

@octogonz
Copy link
Collaborator

octogonz commented Nov 4, 2019

However, this would require something like getLinkFilenameForDeclarationReference(canonicalReference). Is this possible to implement / any ideas on this?

This problem is slightly complicated because we're halfway through a redesign of the declaration reference formalism.

In the old model, API items were identified using TSDoc's DocDeclarationReference which is what you give to ApiModel.resolveDeclarationReference(). But @rbuckton recently redesigned the grammar, and so the canonicalReference field is now represented using his DeclarationReference class from the TSDoc library. The ideal long term solution is to implement an equivalent of ApiModel.resolveDeclarationReference() that uses these canonicalReference objects.

The DocFX implementation was conveniently able to sidestep this part, because DocFX itself supports hyperlinking based on string IDs.

I feel like we could achieve something similar by having ApiModel track a simple mapping from canonicalReference --> ApiItem. (I bet it could also replace the _apiItemsByCanonicalReference map used by YamlDocumenter.) This hack wouldn't support partial lookups yet, but that's not a problem because the .api.json canonicalReference always stores fully qualified forms.

@thorbenziemek I could help with setting up this mapping, if you're able to do the front-end work of emitting Markdown hyperlinks for each token.

@thorbenziemek
Copy link
Author

Thank you @octogonz for the clarification! From what I understand, implementing the Markdown part should be super easy, so I would be happy to help with that part ;).

@octogonz
Copy link
Collaborator

octogonz commented May 6, 2020

This fix was published with API Documenter 7.8.0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
effort: medium Needs a somewhat experienced developer enhancement The issue is asking for a new feature or design change help wanted If you're looking to contribute, this issue is a good place to start!
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants