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.

Sign up for GitHub

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

Jump to bottom

Link to external documentations #1585

Open
FranklinYu opened this issue Nov 7, 2018 · 7 comments · May be fixed by #1669
Open

Link to external documentations #1585

FranklinYu opened this issue Nov 7, 2018 · 7 comments · May be fixed by #1669

Comments

@FranklinYu
Copy link

FranklinYu commented Nov 7, 2018 •
edited

This is a feature request.

It would be awesome if we can link JavaScript built-in types to external documentations like MDN.

current effect

Name Type Description
firstName String the first name

desired effect

Name Type Description
firstName String the first name
@jsdoc jsdoc deleted a comment from LizAinslie May 5, 2019
@jsdoc jsdoc deleted a comment from abdelrahman-gad May 5, 2019
@hegemonic
Copy link
Contributor

You can do something a bit like this with the @external tag, but that's much less elegant than what you're proposing.

If we do this, I think we should provide a more general mechanism for linking directly to external types. See #534 for some (very old, very possibly harebrained) ideas about how we might do this.

@XaserAcheron
Copy link

Kind of a related-ish question, but as a stopgap, is there some sort of 'library' of useful common @external definitions (e.g. native types via MDN) somewhere? This seems like a thing that has to have been created by someone over the years, though my Google-Fu is failing me this morning.

@bcoe
Copy link

bcoe commented Jun 14, 2019

I think this feature would be especially beneficial for exotic types like Promise, or Set, to help introduce folks to new(ish) JavaScript language features.

@filips123
Copy link

If we do this, I think we should provide a more general mechanism for linking directly to external types. See #534 for some (very old, very possibly harebrained) ideas about how we might do this.

I think that JavaScript built-in data types should be automatically linked to MDN documentation (but it could also be configurable).

This should not be hard because all documentation for data types on MDN is on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DATA-TYPE.

I think that it should link data types and some other global objects.

Also, don't forget that users should also be able to write string instead of String. To handle this, you should first convert the written data type to lowercase and then uppercase first letter.

@FranklinYu
Copy link
Author

FranklinYu commented Jul 9, 2019 •
edited

Maybe this can be a plugin? (I got the idea from TypeStrong/typedoc#895.)

@filips123 filips123 linked a pull request Aug 3, 2019 that will close this issue
Open
@klm127
Copy link

klm127 commented Nov 20, 2021 •
edited

Update: I created the plugin. See next comment or see Outerdocs

Old Comment I believe focusing only on MDN core javascript linking is far too narrow a take on this feature and #1669 does not address this.

Sphinx, the python documentation generator, has a tool called InterSphinx which allows linking to other documentation made with Sphinx. Not just base python documentation, but documentation from any project.

This is really relevant when your project has dependencies. It's convenient to be able to quickly click a link to objects that were defined by another library. Not just core javascript objects. In fact, that's likely the least useful feature.

For example I have a Phaser game I'm building. Several of the objects extend Phaser.GameObjects.Image. link

The Phaser documentation is made with jsdoc 3.6.7. You can see that the format of the URLS are really consistent.

It seems that I should be able to create an external reference in my jsdoc file with something like this:

externalDocs: {
  "Phaser": https://newdocs.phaser.io/docs/3.55.2
  }

Then in my comment/docstring I have

@extends Phaser.GameObjects.Image

The parser should search whatever normal source files I've provided for Phaser.GameObjects.Image. But, if it doesn't find the link there, it should look at the externalDocs object with the first part of the name, Phaser. It matches Phaser, sees the URL, then appends The full name of the extended object to the end of the URL and creates a link to it in the documentation.

This doesn't seem like it would be insanely hard to implement. If nobody takes it up, maybe I will try to learn a little more about how jsdoc is coded and see if I can create a plugin for it.

@klm127
Copy link

klm127 commented Nov 23, 2021 •
edited

I created a plugin to link external docs inspired by Intersphinx.

I'll see about making a PR to put it in the default plug ins eventually.

Link: outerdocs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Link built-in objects to external documentation filips123/jsdoc
6 participants
@bcoe @hegemonic @FranklinYu @XaserAcheron @filips123 @klm127