I have a javascript library for communicating with server APIS, written in modern ECMAScript.
It is fully documented with JSDoc comments:
/**
* #class - TODOS API Client class
*/
class todosApi {
/**
* Gets Todos, given the parameters
* #param {number} personId
* #param {number} [year]
* #param {number} [month]
* #param {number} [todoTypeId]
* #returns {Object} - api response object, data will be array of todos
*/
fetchTodos = async (....
}
When using this API in the unit tests in this project, in Visual Studio code, I have excellent intellisense from these comments, and it's a beautiful thing.
However, this library is used by/referenced in a separate react application created with create-react-app. When I run this through babel to transpile into a format that is consumable by my create-react-app app, it ends up like this:
/**
* #class - TODOS API Client class
*/
class todosApi {
_defineProperty(this, "fetchTodos", async (personId, eventYear, eventMonth, todoTypeId) => {
}
And I lose my intellisense for fetchTodos, and actually the class itself because of how it is exported in and index.js file. babel does have the option to include comments by default, however the class gets a little mangled in transpiling and loses some comments.
Is there any way to transpile and still preserve this intellisense for VS Code?
Use tsd-jsdoc to create a types.d.ts file.
In your package.json add a script to run ...
jsdoc -r src -t node_modules/tsd-jsdoc/dist -d lib
And set types to lib/types.d.js.
Include that script as part of prepublishOnly so it runs before every npm publish.
Related
What I would like is to write something like this:
/**
* Takes a foo and {#link grokelates} it.
*/
function doSomething(foo) {
}
And have "grokelates" be a link to more detail on what "grokelate" means, but because I'm going to have functions dealing with grokelation all over my code base, I'd like to write that definition once and link to it in multiple places.
Is this possible?
To be clear, grokelates is not a function. It's just a word I want to define, but not have to define in-line everywhere I use it. I basically want to write a glossary file and be able to link to definitions from that glossary in my JSDoc.
Ideally this would also be in a way the VS Code picks it up and lets someone navigate to that definition on hover.
Yes there is. When you run jsdoc to generate your documentation, you can pass it any filetype you wish. A standard practice is to create one or more *.jsdoc files which contain doclet comments (those that begin with /**) to describe features you expect to use elsewhere in your code. For instance:
// filename: grokelation.jsdoc
/**
* #module grokelates
*/
/**
* #name Grokelate
* #memberof module:grokelates
* #description
* Here is the description of the grokelation process.
*
* #example
* var g = new Grokelate(opts);
*/
Then, when you wish to reference this new object elsewhere in your documentation, simply use its long name module:grokelates~Grokelate where you can consider the ~ glyph to mean "member of".
In your example above, you'd say {#link module:grokelates~Grokelate}.
I would like to know if there is any way to get all the scripts parameters when you create a new script (SuiteScript 2.0) using VS Code.
I'm aware that it is possible when using Eclipse IDE but I do really would like to keep using VS Code as I'm already using for Python and JavaScript.
This is what I'm looking for:
/**
* Function definition to be triggered before record is loaded.
*
* Task #5060 : calculate PO Spent Amount and Balance in realtime
*
* #param {Object} scriptContext
* #param {Record} scriptContext.newRecord - New record
* #param {Record} scriptContext.oldRecord - Old record
* #param {string} scriptContext.type - Trigger type
* #Since 2015.2
*/
BTW, I'm already using VS Code Intelisense and NetSuite Uploader extensions.
Thanks
At the time of writing, there are no official plugins from Netsuite for VS Code, only Eclipse & Webstorm are available. However, there is an unofficial plugin from Head-in-the-Cloud that might do what you're after.
I want to specify a type in one file, and be able to reuse it in another one. I tried modules but it didn't work in VS Code. Is there any other solution? Just wanna have all types for my project to be reusable so I can reference them in different functions across files. This is the closest question I have found.
I've had some success with using jsconfig.json and its include property in a plain JavaScript project in Visual Studio Code 1.33.1
{
"include": [
"src/**/*.js"
]
}
Given the following JavaScript project:
src/
├── types/
| ├── person.js
| ├── question.js
|
├── answer.js
├── jsconfig.json
Where both question.js and person.js are type definitions:
person.js
/**
* #typedef {object} Person
* #property {string} firstName
* #property {string} lastName
*/
question.js
/**
* #typedef {object} Question
* #property {Person} askedBy
* #property {string} text
*/
And answer.js is a function that accepts a question and return an answer:
/**
* Takes a question and return an answer
* #param {Question} question
*/
function answer(question) {
return 42;
}
As you can see in the first screencast I do get IntelliSense support when hovering over the Question type notation:
On top of that IntelliSense is also now able to offer code completion based on my types definitions:
Since TypeScript 2.9 which is embedded in the newer VS Codes, it is possible by using the import syntax in JSDoc, like so
/**
* #typedef {import("koa").Context} Context
*
* #typedef {Object} BodyparserOptions
* #prop {(ctx: Context) => boolean} [detectJSON] Custom json request detect function. Default `null`.
*/
Also VS Code should be picking up all types defined across the workspace.
I'm trying to generate a doxygen document where I have two documentation instances for functions. One describes the usage(interface) of the functions that get pulled from the function header in the .h file and the other describes implementation of the function that gets pulled from the .c file. I basically want to describe the same function in two different ways based on where the file that the description came from(.h or .c). I thought this would help the usability of the document since you can easily ignore the implementation details if you only care about how to use the functions. My best attempt was to try to add the .h and the .c files to separate groups like this.
example.h
/**
* #defgroup exampleInterface Example Interface
* #{
*/
/**
* This is the header file so I describe how to use this function
* #param arg
* #returns something
*/
int someFunction(int arg);
/**
* #}
*/
example .c
/**
* #defgroup exampleImpl Example Implementation
* #{
*/
/**
* This is the .c file so I describe how this function is implemented.
*/
int someFunction(int arg)
{
... Some code ...
}
/**
* #}
*/
The result was that the function header descriptions were still combined. Is there anyway to accomplish this in doxygen? Maybe there is another way I should look at this problem.
Thanks.
A possible hack you could try is to use the #internal command for the implementation which would mean you would run doxygen twice: once without the internal (for the external definitions) and the other with the inernal which would combine them.
I'm trying to document a Javascript file with JSDoc(3) like so:
/** 1 if gnome-bluetooth is available, 0 otherwise
* #type {boolean}
* #const
*/
const HAVE_BLUETOOTH = #HAVE_BLUETOOTH#;
Now the file (called config.js.in) is not on its own valid Javascript; the file gets run through a Makefile which substitutes an appropriate value for #HAVE_BLUETOOTH#.
When I try to run JSdoc on this, it (understandably) balks because of the syntax error in the file.
Is there some way to tell JSDoc to ignore all code in this file but simply take into account the annotations? (I might have to add #name tags to each doclet to completely separate the documentation from the code; that's fine).
Something like:
/** 1 if gnome-bluetooth is available, 0 otherwise
* #name HAVE_BLUETOOTH
* #type {boolean}
* #const
*/
/** #ignore */ // somehow ignore from here onwards
const HAVE_BLUETOOTH = #HAVE_BLUETOOTH#;
/** !#ignore */ // somehow don't ignore from here onwards (although I'd be happy
// to ignore the entire file)
I'd prefer not to modify the code part of the file, if possible (I'm adding documentation to an existing project). For example, I could probably get around it with
const HAVE_BLUETOOTH = parseInt('#HAVE_BLUETOOTH#', 10);
which would make the file have valid JS syntax again so that the parser doesn't complain, but this also means I'm modifying the code of the original file which I want to avoid (I prefer to just add documentation).
cheers
My case is similar because I use JSDoc to comment my .less and .css file. When I running JSDoc on set of file, I have the same issue.
So, I resolve my problem (with JSDoc 3.3.3) with the commentsOnly JSDoc plugin
https://github.com/jsdoc3/jsdoc/blob/master/plugins/commentsOnly.js
I have create this config.json:
{
"source": {
"includePattern": ".+\\.(css|less)?$"
},
"plugins": [
"plugin/commentsOnly"
]
}
with the commentsOnly.js file into a plugin/ directory (consider plugin/ and config.json are in same folder) and in this folder I execute the following CLI command:
jsdoc -c ./config.json ./assets/stylesheets/common.less
And it's work ! There are no reason this do not work with your files.
Hope I help you ;)