search

microsoft / tsdoc

A doc comment standard for TypeScript
https://tsdoc.org/
MIT License
4.74k stars 131 forks source link

Add support for the `@see` tag #236

Closed 0xCLARITY closed 4 years ago

0xCLARITY commented 4 years ago

We use eslint-plugin-tsdoc in some of our projects, but we also use @see tags. I would like to be able to keep using both of these. This PR would address https://github.com/microsoft/tsdoc/issues/235.

This is blatantly stolen from https://github.com/microsoft/tsdoc/pull/205. @rbuckton , if you have any feedback, please let me know.

The 205 PR claims that implementing @see tag is blocked on adding support for synonyms, but in the JSDoc @see tag documentation it does not have a synonym listed. So, I thought we would be able to implement @see tag functionality without building synonyms.

I'm a little in over my head here, but I'm happy to learn.

msftclas commented 4 years ago

CLA assistant check
All CLA requirements met.

Gerrit0 commented 4 years ago

Both of these will link to the bar function. @see {@link bar} @see bar

This seems to go against TSDoc's philosophy of one obvious way. I prefer the first since it seems reasonable to want to write @see {@link bar} for why the world is round.

rbuckton commented 4 years ago

I already have a PR to address this: https://github.com/microsoft/tsdoc/pull/205

rbuckton commented 4 years ago

One of the reasons to support both forms is to support existing documentation when someone is migrating from JavaScript to TypeScript.

0xCLARITY commented 4 years ago

I already have a PR to address this: #205

Definitely didn't mean to step on your toes, and this PR is mostly just copy-pasting some relevant stuff from your PR.

My reasoning for creating a new PR is that #205 appears to be blocked on implementing synonyms in TSDoc, but looking at the JSDoc @see tag documentation I don't see any synonyms listed for the @see tag. Am I missing something?

rbuckton commented 4 years ago

You're not missing anything. seealso mostly comes from XML doc comments in C#. You're correct that synonyms aren't strictly necessary for this feature, but I still believe supporting both @see {@link foo} ... and @see foo ... are useful for anyone coming from using the jsdoc app to generate their documentation. If tsdoc would rather its users choose a single syntax, it might be feasible to still support @see foo ... with a warning (which could be disabled by tools like api-extractor, etc.).

octogonz commented 4 years ago

I added some comments in https://github.com/microsoft/tsdoc/issues/235

Let's agree on the spec before we merge a PR.

octogonz commented 4 years ago

@hbergren Based on the thread in https://github.com/microsoft/tsdoc/issues/235 I've proposed some changes in PR https://github.com/hbergren/tsdoc/pull/1 into your branch.

Could you promote this PR to non-draft so we can get it merged? @see seems like an easy addition and a valuable feature.

0xCLARITY commented 4 years ago

Based on the thread in #235 I've proposed some changes in PR hbergren#1 into your branch. Could you promote this PR to non-draft so we can get it merged? @see seems like an easy addition and a valuable feature.

Approved that PR with one question just to double-check my understanding.

0xCLARITY commented 4 years ago

@octogonz, I approved and merged your PR for see-tag. Let me know what else I can do to help move this forward.

octogonz commented 4 years ago

@hbergen Thanks again for making this PR! It was published as TSDoc 0.12.20.