0

I think it looks messy and harder to read when JSDoc is mixed into regular (JS) code. Is it possible to add the documentation to an external file & reference the functions there (and have Visual Studio's "preview" of parameter types & return values work properly by using the JSDoc)?

What do I have to do to make this (or something similar) work?

I'm thinking something like this (3 files).

myfile.html

...
<body>
    ...
    <script src="./JSDock.js"></script>
    <script src="./script.js"></script>
</body>

JSDoc.js

/**
 * @function test
 * @param {string} myText
 * @return int
 * What more should be here?
 */

script.js

function test(myText) {
    return 5;
}
Sebastian Norr
  • 7,686
  • 2
  • 12
  • 17
  • You can collapse the block comment if you have a good editor. – Patrick Roberts Jul 13 '20 at 08:54
  • 2
    This question is legit, but I would advise against doing this. The very point of JSDoc is to have it inside the code, so it's right next to the implementation, making it much more likely that people will remember to add/update documentation if they change something. You can configure your editor to hide or collapse doc comments, or barring that, render them in a dim, unobtrusive colour. – Thomas Jul 13 '20 at 08:55
  • @Thomas It might be a bad idea, but I still prefer to completely remove the JSDock from the JS code & move it into it's own file. Not just hide it. – Sebastian Norr Jul 13 '20 at 08:58
  • Maybe you can use [`@external`](https://jsdoc.app/tags-external.html). Not posting this as an answer because I'm not sure and haven't tested it. – Thomas Jul 13 '20 at 09:00
  • @PatrickRoberts Se comment above, I'm not allowed to @ more than one person. – Sebastian Norr Jul 13 '20 at 09:00
  • @PatrickRoberts I tried that, it didn't seam to work, but I'm not sure if I did something wrong. The documentation states: **"class, namespace, or module** that is defined outside of the current package." and I'm trying to document a **function,** I don't know if JSDock treat them differently? (and the documentation is kind of confusing to me) – Sebastian Norr Jul 13 '20 at 09:03

0 Answers0