jsdoc hide Inherited method (in generated doc) - javascript

I'm using jsdoc to generate online doc for my javascript project.
It works fine except one problem I'm having right now.
Say I have a base class with lots of get/set functions.
/**
* cc.BaseClass
* #class
* #extends cc.Class
*/
cc.BaseClass = cc.Class.extend(/** #lends cc.BaseClass# */{
/**
* #param {number} a
*/
setA:function(a){},
/**
* #return {number}
*/
getA:function(){},
// ...... 20+ more
});
Then I have a child class which extends the base class.
/**
* cc.ChildClass
* #class
* #extends cc.BaseClass
*/
cc.ChildClass = cc.BaseClass.extend(/** #lends cc.ChildClass# */{
/**
* #param {number} xxx
*/
myFunction:function(xxx){}
});
My problem is the generated online DOC for the cc.ChildClass contains the "myFunction:function" along with the 20+ get/set functions inherited from the cc.BaseClass.
I know there is nothing wrong about this but I want to know if there is a way to hide all the 20+ get/set functions inherited from the cc.BaseClass in the doc for cc.ChildClass.
Think if I have cc.ChildClassA cc.ChildClassB cc.ChildClassC ... then I don't want to see each of their doc contains the 20+ get/set functions inherited from the cc.BaseClass.
Any suggestion will be appreciated, thanks :)

You shoudn't adapt your code / classes for satisfying this. This should be the responsiblity of the template. This one does the trick very well: https://github.com/steveush/foodoc - demo: https://cancerberosgx.github.io/jsdoc-templates-demo/demo/foodoc/Apple.html . Another one that supports it is ibm's amddcl. In the following look for https://cancerberosgx.github.io/jsdoc-templates-demo/demo/amddcl/Apple.html#
Some other templates dont show inherithed at all and dont allwo the user to toccle - which I also dont want. I think foodoc allows both the user and the compiler-person to configure it nicely.
BTW I'm trying to collect well known jsdoc templates demos here https://cancerberosgx.github.io/jsdoc-templates-demo/demo/ - for each there are installation instructions.

Only thing I could come up with is to remove #extend. I added a link to the extended class manually to the description. This works for me in this instance because I do not need #extends for anything else.

Related

Why would HtmlUnitDriver not Locate WebElements but FirefoxDriver able to locate the same WebElements

I have a question.
What makes FirefoxDriver be able to locate WebElements and click on them in a java code but when running the same code with HtmlUnitDriver the same WebElements are not located. Also when running the same code on HtmlUnit(applying HtmlUnit principles) WebElements are not found, in fact the code return NullPointerException. Is there a particular reason?
Without seeing your code, I might hazard a guess that it might be because you need to enable javascript.
JavaScript is disabled by default in the HtmlUnitDriver.
If you look at the source constructor at(LICENSE Apache 2.0)
https://github.com/SeleniumHQ/htmlunit-driver/blob/master/src/main/java/org/openqa/selenium/htmlunit/HtmlUnitDriver.java#L166
/**
* Constructs a new instance, specify JavaScript support
* and using the {#link BrowserVersion#getDefault() default} BrowserVersion.
*
* #param enableJavascript whether to enable JavaScript support or not
*/
public HtmlUnitDriver(boolean enableJavascript) {
this(BrowserVersion.getDefault(), enableJavascript);
}
And the other constructors at https://github.com/SeleniumHQ/htmlunit-driver/blob/master/src/main/java/org/openqa/selenium/htmlunit/HtmlUnitDriver.java#L143-L158
/**
* Constructs a new instance with JavaScript disabled,
* and the {#link BrowserVersion#getDefault() default} BrowserVersion.
*/
public HtmlUnitDriver() {
this(BrowserVersion.getDefault(), false);
}
/**
* Constructs a new instance with the specified {#link BrowserVersion}.
*
* #param version the browser version to use
*/
public HtmlUnitDriver(BrowserVersion version) {
this(version, false);
}
You see that they provide a default false if the variable isn't provided.
So to enable javascript in the HtmlUnitDriver you'll need to provide true when initializing it, that you want JavaScript components active in it.
WebDriver driver = new HtmlUnitDriver(BrowserVersion.FIREFOX_38, true);

PhpStorm JS inspection - JS variable coming from backend

I wanted to take some time to "clean" a personal app, to remove most of the warnings, etc.
As stated in the title I use the PhpStorm IDE and I have some warnings "Unresolved variable slug" when I use series.slug. The variable series comes from either a JSON from a PHP Class or after an Ajax call.
Is there a way to indicate an object's properties or to link a js variable to a PHP class (like in Twig)?
P.S. In my "Settings > Languages > JS > Code Quality Tools", I have nothing enabled, I just have the "basic" PhpStorm inspection.
If you use some object with keys only known in runtime (generated, received through the ajax call, etc.) in your code, there is no way for the IDE to resolve them using static code analysis.
But you can let the IDE know what your runtime data looks like. Possible solution using JSDoc annotations:
/**
* #typedef {Object} series
* #property {string} slug
* ... other series props here....
*/
...
/**
* function that uses series data
* #param {series} data
*/
function foo (data){...}
See also https://youtrack.jetbrains.com/issue/WEB-17419#comment=27-1058451, https://intellij-support.jetbrains.com/hc/en-us/community/posts/206349469-disable-unresolved-variable-on-json-object-received-by-ajax-call for other possible workarounds

JSDoc: Why aren't my nested objects links (why aren't they click-able)?

I would think that all members / objects / etc. documented by JSDoc should be their own click-able links; e.g., if I have levelOne --> levelTwo --> levelThree --> levelFour, then I should see levelOne on the first page and be able to click my way through to levelFour...but that doesn't seem to be the case.
Here is my code:
/**
Contains various tools and extensions.
#namespace App
*/
var app = app || {};
/**
Contains App plugins.
#namespace App.Plugins
*/
app.Plugins = app.Plugins || {};
/**
Contains methods and classes usable within unit-testing.
#memberof App
#type {object}
#namespace App.UnitTesting
*/
app.UnitTesting = app.UnitTesting || {
/**
Test methods for the App library.
#memberof App.UnitTesting
#type {object}
#property {object} test1 Property definition.
*/
PluginTests: {
/**
Test for this or that
#memberof App.UnitTesting.PluginTests
#type {object}
#property {method} innertest1 Property definition for "innertest1"
*/
test1: {
/**
Run another nested test
#memberof App.UnitTesting.PluginTests.test1
#method innertest1
#returns {object}
*/
innertest1: function () { }
}
}
};
The "namespace" objects are easily clickable, and are accessible from the home page, but PluginTests IS NOT CLICKABLE (IT ISN'T A LINK!!), and therefore test1 and innertest1 are not accessible. Am I grossly misunderstanding how JSDoc works?
PS: Before anyone starts tearing apart my code with hurtful comments, please note that I learned of JSDoc's existence about 3 hours ago and am very new to this.
As far as I know, JSDoc doesn't generate pages for all or an arbitrary property. You might expect JSDoc to generate pages for deeply nested object properties automatically, but that isn't the case. For example, there is an open issue on Github on making it easier to link to object properties.
The JSDoc output for the UnitTesting namespace in the code you provided looks as following (using the default template):
I assume that you expected the property test1 to be clickable and that it would lead you to a page providing information on test1 (eg. the fact that it has a method innertest1). Unfortunately, that isn't the case.
The way code is documented is slightly related to its architecture (eg. JSDoc provides support for classes, modules, mixins, namespaces, and so on). In my experience, good architecture helps writing neat documentation. The JSDoc template you use might influence how your perceive hierarchy. For example: some templates create a tree of namespaces.
Anyway, in this particular example/architecture, your options are:
Adding another #namespace for PluginTests.
Adding a #property entry for innertest1 in the PluginTests doclet.
Examples coming up.
1: Add a #namespace
Adding a #namespace to PluginTests would result in another namespace page, specifically for PluginTests, and would include the information you need:
The change to the code you provided is obvious, yet I'll just include the part that changed for the sake of completeness:
/**
* Test methods for the App library.
* #namespace App.UnitTesting.PluginTests
* #memberof App.UnitTesting
* #type {object}
* #property {object} test1 Property definition.
*/
PluginTests: {}
2: Add #property for innertest1
Instead of creating another namespace, you could document the property test1.innertest1 in the PluginTests doclet:
/**
* Test methods for the App library.
* #memberof App.UnitTesting
* #type {object}
* #property {object} test1 Property definition.
* #property {method} test1.innertest1 A method.
*/
PluginTests: {}
This would result in an extra property table inside the description of test1:
Side note
You might like using the Baseline template to format your documentation. It's still under active development (by Googlers) and subject to change. One of the reasons I occasionally use it: it's easier to navigate. From the docs:
An expandable table of contents helps users find what they're looking for. Also, a summary at the top of each page shows users what's documented on that page.
One downside is that Baseline doesn't support the second option yet.

Is there a way to force NetBeans JavaScript Autocomplete?

I am developing some JavaScript to be used in a CMS I'm working on.
I have encapsulated my code like this:
(function(){
var libraryName = {};
...code...
window.libraryName = libraryName;
}())
Now when I add a subnamespace and try using it outside my declaration, the NetBeans (8.0.2) autocomplete function doesn't work. Like this:
(function(){
var libraryName = {};
libraryName.subSet = {
showSomething: function(){}
};
window.libraryName = libraryName;
}())
libraryName.subSet.showSomething(); // This works
libraryName.subSet. // No current autocomplete even when pressing CTRL+space
I would like to know if there is some way to tell NetBeans how to autocomplete instead of it guessing.
Thanks
You can use Ctrl+K, the "hippie" code completion. It directly completes some matching result and if the completed item is not what you wanted, you can keep pressing Ctrl+K to get another autocompleted item (will replace the previously inserted one). Another thing, you can press Ctrl+Space 2 times to get "full" code completion (meaning pretty much everything from other objects/variables)
Update: There is another way using JSDoc, but it works only in Dev build of NetBeans and will be part of the next 8.1 release (you can download Dev builds from here):
/**
* #typedef libraryName
* #property {Function} showSomething description
* #property {someProp} foo description
*/
/**
* #typedef someProp
* #property {Date} day description
* #property {Number} num description
*/
/**
* #typedef libraryName.someProp2
* #property {Date} day description
* #property {Number} num description
*/
This way you'd have to create this "documentation" for your library and have it somewhere in JS file in your project (perhaps non-minified JS file of your library). With this #typedef feature, you can learn code completion pretty much anything even if it is not even in your code). Of course there are some issues yet to be fixed (it is a Dev build)...
I tried another approach which worked for me.
I copied my JavaScript file and removed the encapsulation. So I now have two files, the "real" one with the encapsulation and another "working" one that doesn't have the encapsulation. Now when I try using the autocomplete it works.
The downside for this is that you create noise since there is a file that isn't meant for the web app and you have to update it every time you update the original file. But it makes coding easier with the magic of autocomplete. When you load html you just don't reference the "working" file.
So, this would be my main.js file (in /js/main.js for instance)
(function(){
var libraryName = {};
libraryName.subSet = {
showSomething: function(){}
};
window.libraryName = libraryName;
}())
And a main.tmp.js file would be like this (in /tmp/main.tmp.js for instance)
var libraryName = {};
libraryName.subSet = {
showSomething: function(){}
};
Now, when I do libraryName.subSet. it shows me the correct autocomplete with showSomething.

JSDuck - Created document that doesn't show any parameters of function

Example:
There are several .js files with couple functions like:
/**
* TestFunction - doing something.
* #param {String} strTest Test string.
* #return {Boolean} bRes Returned value.
*/
function TestFunction(strTest) {
//code ...
return bRes;
}
After JsDuck.exe created help file - no parameters of function in function description is present, only return value bRes with description.
Version: SDuck 5.0.0.beta2 also tried on earlier version and same result.
Does anyone used JSduck for functional frameworks and got success. or are there any workaround to get this work properly?
Same .js files work correctly with JSDoc toolkit and all data is shown, but JSDuck is still preferable to make it work.
Thanks in advance for reply.
Answered your question in bug-tracker: https://github.com/senchalabs/jsduck/issues/358

Categories