I'm an absolute newcomer to JSDoc and the Javadoc-like conventions; I am looking for some low-hanging fruit to get up and running, and I'm coming up short.
My code is organized like this, primarily as a matter of personal style:
var app = app || {};
app.ui = {
someUIfunction: function() {},
someUIparams: {},
anotherFunction: function(string, object) {}
}
app.rest = {
someRESTCall: function(url,data) {},
someRESTparams: {},
moreRESTCall: function(url,data) {}
}
Theoretically everything could just be one monolithic object under "app", but I like breaking down the next-level objects separately for handy cold-folding and searching in the IDE. Plus it just feels tidy to me that way.
What I cannot manage to do is drill down into the third-level functions and objects. JSDoc3 doesn't seem to want to render it for me; moreover, I'm not in love with having a starting page that is just "app" (or whatever I give the app in the end) as the namespace... I want its members to be in the index as well. Here's my attempt (forgive the silly examples!):
/**
* Application Namespace for this marvellous application
*
* #namespace app
*/
var app = app || {};
/**
* An object containing methods and parameters used for UI presentation logic
*
* #type {object}
* #memberOf app
* #property {string} title - a string used as the title of the UI
* #property {function} init - a function to initialize the UI
*/
app.ui = {
// not bothering to document this for whatever reason
title: "some title",
/**
* #memberOf app.ui
* #params {object} params - an object containing necessary initialization parameters
*/
init: function(params) {
// some initialization logic
}
}
There are two problems:
Ideally I'd like app.ui to have its own page. Is #namespace the right way to do this? It works, but visually it masquerades in the Index as being at the same level as app itself.
app.ui.init isn't documented at all.
It seems to me (and admittedly, this is probably just ignorance!) that JSDoc3 would be happier if I were to use:
app.ui.init = function() {} // (etc)
But that's going to be rather ugly as far as I'm concerned. Any pointers for the syntax I need to use to indicate nested members is what I'm after.
Related
I have a simple custom module which posts messages to a server-side Suitelet.
/**
* test_app_client_module.js
* #NApiVersion 2.x
* #NScriptType ClientScript
* #NModuleScope SameAccount
*/
define(['N/ui/message'], function(message) {
var exports = {};
function showMessage(messageObject) {
message.create(messageObject).show();
};
exports.showMessage = showMessage;
return exports;
});
This module functions properly when used with form.ClientScriptModulePath and invoked from a file cabinet, excluding #NScriptType.
However, if I attempt to create a script record to define this module in a remote function, I get the following error.
SuiteScript 2.0 entry point scripts must implement one script type function.
Any suggestions?
As the error message states, you haven't implemented an entry point function. All Script modules need at least one entry point.
Add an empty pageInit function to your module.
exports.pageInit = function () {}
Can I define all custom types in a separate file (e.g. types.jsdoc), so that they can be reused throughout the application? What's the right way to do it?
/**
* 2d coordinates.
* #typedef {Object} Coordinates
* #property {Number} x - Coordinate x.
* #property {Number} y - Coordinate y.
*/
You can define types in a module (eg. typedefs.js). The module contains your JSDoc typdefs and can simply export an unused property.
// typedefs.js
/**
* #typdef foo
* #property {string} bar
*/
// etc.
exports.unused = {};
To use it, import the module where you need to reference these typdefs:
const typedefs = require("./typedefs");
/** #type {typedefs.foo} */
const fb = { bar: "hello" };
You may wish to annotate typedefs.js as a #module or #namespace. Because I'm using "tsd-jsdoc" to generate a types.d.ts file, and due to the way TypeScript now interprets modules vs. namespaces, I've annotated my typedefs.js file as a #namespace and documented each typedef as a member of that namespace:
/**
* #namespace typedefs
*/
/**
* #typedef foo
* #property {string} bar
* #memberof typdefs
*/
Hope that helps.
This is a TypeScript-flavored JSDoc specific answer, but I'm having success using a triple-slash directive to "import" all the types from another file. This has the advantage of not actually adding an unused import which can upset linters and bundlers.
I'm putting my shared types in one file called typedefs.js like this:
// typedefs.js
/**
* #typedef {Object} Foo
* #property {string} bar
*/
/**
* #typedef {Object} Baz
* #property {number} buzz
*/
and then using /// <reference path="typedefs.js" /> in the other files to access the shared types like this:
// randomThing.js
/// <reference path="typedefs.js" />
/**
* Turn a Foo into a Baz
*
* #param {Foo} a
* #return {Baz}
export function (a) {
return { buzz: a.bar.length };
}
The tricky thing though is that now typedefs.js is just being referenced in a comment, bundlers like rollup miss it completely. So I'm combining it with my old consts.js that exports a few constants and is imported in at least one place. That way the typedefs are still included in the rollup output.
I hope someone else finds this helpful.
p.s. rollup will completely exclude a pure JSDoc typedefs.js file _even if you have import './typedefs.js' because of tree-shaking! Gotta run rollup with --no-treeshake to keep those comments in the rollup output.
In vscode, the import('./path/to/types.js').def tag works perfectly fine.
For e.g.
types.js
/**
* #typedef {Object} connection
* #property {String} id
* #property {Number} pingRetries
* #property {(data:Object) => void} sendJSON
*/
exports.unused = {};
And someFile.js
/**
* #param {import('./types').connection} param
*/
const someFunc = (param) => {}
Also, note that the exports.unused = {} is necessary in the types.js file, otherwise the auto-import of import('./types') would not work and you may have to type it by yourself.
I just tried with VSCode and it works only if the separate file is opened in the editor. If not, external typedefs are typed as any
I usually do something similar in my projects, the difference being I use the extension .js to name the file. Webstorm works perfectly and is able to check types and auto-complete just fine. It won't recognize the .jsdoc extension (I just checked), so stick to .js even if the file doesn't contain any code statement.
I've had success with simply creating my types in a typedefs.js file and referencing using the ts/vscode import(path/to/file).Foo tag. JSDoc does not support this syntax out of the box, so I suggest also using jsdoc-tsimport-plugin in order to parse your docs.
Eg: typedef.js:
/**
* #typedef {Object} Foo
* #property {string} id
*/
/**
* #typedef {Object} Bar
* #property {string[]} things
*/
// having to export an empty object here is annoying,
// but required for vscode to pass on your types.
export {};
coolFunction.js
/**
* This function is super dope
* #param {import('../typedef').Foo[]} foo - a foo
* #return {import('../typedef').Bar[]} bar - an array of bars
*/
export function (foo) {
// do cool things
return bar;
}
I'm also using tsd-jsdoc to create a types.d.ts file, and this implementation is successfully creating the types. I had trouble with declaring modules and namespaces with the types file— just creating standalone typedefs for said models worked best for me.
I have been having a hard time getting the #borrows tag working in JSDoc. I have been trying to get the documentation from one function and us it as documentation for a second function. But I don't seem to be able to even get a simple example working!
/**
* This is the description for funcA
*/
var funcA = function() {};
/**
* #borrows funcA as funcB
*/
var funcB = function() {};
I was expecting this to output documentation for both functions with both exactly the same. However only funcA is only has a description.
The #borrows tag doesn't seem to work directly on a symbol, but only indirectly. For example I had:
/** does amazing things */
function origFunc = function() {};
/**
* #borrows origFunc as exportedFunc
*/
exports.exportedFunc = origFunc;
but I, like you, got nothing useful in the generated doc.
That is because, it seems, that the #borrows tag operates on a container. (If you'll notice in the examples the #borrows tag is on the "util" module/namespace, not the renamed symbol.)
So this worked for me:
/** does amazing things */
function origFunc = function() {};
/**
* #borrows origFunc as exportedFunc
*/
exports = {
exportedFunc: origFunc,
}
Seems like a bug in #borrows though. (Or at least a bug in the documentation.)
I recently had a usage of it, what I was trying to do is to create a module and add some functions to it. The problem is that I don't have anything directly related to this module, since the export is just a line. Here's how I ended up with using #borrows.
/**
* A typehead with options filtered by user input.
*
* #module Typehead
* #borrows Typehead
* #borrows TypedOption
* #example
* <Typehead />
*/
export { default } from './Typehead'
In this case, Typehead will be borrowed in either Function or Classes section of module page depending on the kind of Typehead, and it will be displayed under #example render.
Note: However #borrows will add some extra entries to the system, after some experimentation, maybe #see is a better use.
In a separate Page Object file (not in the actual file with tests) I'm trying to do something like:
this.item0 = element.all(by.repeater('menu items')).get(0);
This won't work because the code is executed before the tests are run. I haven't found another way of doing this except to call get() in the test file (which I don't want to do). Is there a way to do this in the Page Object file?
This behavior often confuses people who are trying to write page objects.
Your locator will not be executed until you call a function on the elementFinder or the elementArrayFinder (see https://github.com/angular/protractor/blob/master/docs/api.md).
I usually use this pattern:
// Page object
MyView = function() {
// This will not find elements until you call count(), get(), first(), etc.
this.itemList = element.all(by.repeater('menu items'));
};
module.exports = new MyView();
// Test
// Require the page object at the top of the test file.
var myView = require('./my-view.js');
// Use the page object in the test.
it('should get first element', function() {
myView.itemList.get(0).then(function(webElement) {
})
});
The following is from source code for ElementArrayFinder.get
/**
* Get an element within the ElementArrayFinder by index. The index starts at 0.
* This does not actually retrieve the underlying element.
*
ElementArrayFinder.prototype.get = function...
So Apparently you should be able to call it from within the page object even before the elements are loaded.
yay, i'm not the only one using page objects ;)
i did the following:
var MyPage = function () {
this.item0 = element.all(by.repeater('menu items')).get(0);
}
in my tests:
describe('MyPage:', function () {
var myPage = new MyPage();
// after this line navigate your browser to your page
// then you can call myPage.item0, myPage.whatEver
}
I'm trying to integrate some testing into my current Backbone/CoffeeScript application.
I have created a module for my application baked into the window object, but running any mocha tests fail because window is undefined.
module = (name) ->
window[name] = window[name] or {}
module 'Cart'
Any direction as to how I can define window for mocha?
I did try using jsdom and creating a window that way, but it still threw the same error. Thanks in advance.
EDIT:
Using zombie.js is getting me further then using jsdom.
zombie = require 'zombie'
browser = new zombie.Browser
browser.window.location = 'http://local.cart'
I'm trying to figure out a way to access the DOMWindow and set a variable to one of its values.
It would be ideal if browser.window was the same object as returned from accessing window in Chrome console, but it isn't.
I can access what I'm looking for with
zombie.visit 'http://local.cart', (err, browser) ->
throw err if err
browser.window.Cart
Is there a way for me to set what this returns to a global variable I can use throughout all of my specs?
Can't seem to get what I want trying a beforeEach or setting the previous block to a method and setting a variable to that method.
I think you'll definitely want to mock window, as opposed to trying to pass around a real DOM window object in the node side of your app (mocha).
Try this pattern I just whipped up (sort of conforms to mocha tutorials I have read and uses the this context which changes when in browser (window) vs. run on node (exports):
/**
* My namespace is 'AV'
*/
(function(root) {
/**
* #namespace root namespace object
*/
root['AV'] = root['AV'] || {};
var AV = root['AV'];
AV.CoolThing = {
//...
};
// this will give you
// your "window" object
// which is actually
// module.exports
return root;
})(this);
Then, the test might look something like this (mine are in coffeescript too):
chai = require 'chai'
chai.should()
# exports / "window"
{ AV } = require '../src/AV.js'
describe 'Sample test with namespace', ->
it 'should be an object', ->
AV.should.be.an 'object'