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;
}
Related
Here in my code in my ASP.NET Core project I have that's causing the issue:
As Text:
<script>
/**
* Get a setting value.
* #param {string} name
* #param defaultValue
* #returns {*}
*/
getSetting(name, defaultValue) {
return name in this.settings ? this.settings[name] : defaultValue;
}
</script>
The error that I'm getting for every documentation code, which is red lined is https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/cs0103
which gets clearly identified as C# code, even though I'm writing this code in a .cshtml file <script> tag...
How do I fix this? It prevents me from compiling and executing...
I am using Visual Studio 2022 Preview 4.1 if that matters
.cshtml files are interpreted as Razor templates where # is used to mark C# code in the template.
You can either escape with a second # i.e. ##param etc or move the JS to a separate file.
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
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.
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.
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