I use PHP's reflectionclass to write my own API documentation generator where it generates Documentation for some functions and classes by getting the Doc Comments attached to them and parsing it.
Now I need to do the same in Node.js. Is there a built-in JavaScript function that can find JSDoc comments of a specific identifier? I mean without having to write code to manually parse the source code as in this JSDoc regex question asked earlier
I need something just like in this PHP example
<?php
/**
* A test class
*
* #param foo bar
* #return baz
*/
class TestClass { }
$rc = new ReflectionClass('TestClass');
var_dump($rc->getDocComment())
?>
Output:
string(55) "/**
* A test class
*
* #param foo bar
* #return baz
*/"
Related
I am trying to write a MediaWiki Search Hook that will list native files in the file system and then, eventually, allow a person to click on one of the files and view its content.
My extensions.json contains this:
"Hooks": {
"SearchAfterNoDirectMatch": "MediaWiki\\Extension\\NativeFileList\\Hooks::onSearchAfterNoDirectMatch"
},
My Hooks::onSearchAfterNoDirectMatch file looks like this:
namespace MediaWiki\Extension\NativeFileList;
class Hooks {
/**
* #see https://www.mediawiki.org/wiki/Manual:Hooks/SearchAfterNoDirectMatch
* #called from https://gerrit.wikimedia.org/g/mediawiki/core/+/master/includes/search/SearchNearMatcher.php
* #param $searchterm
* #param $title - array of titles
* Returns true if it found something, false is otherwise
*/
public static function onSearchAfterNoDirectMatch( $searchterm, &$title ) {
$title=Title::newFromText( "test", "bar");
return false;
}
}
My problem is that no text is returned. Well, it's worse than that. With the above code, I get an exception (but I don't know how to debug it, because I can't see the exception). If I take the line setting $title out, it returns. If i change the line to $title=undefined(); I get another error. If I set $title="foo"; I get no error, but no foo.
So how do I return a search hit or, even better, a set of search hits?
None of the existing search plug-ins use the modern search Hook api, which is documented in these locations:
https://www.mediawiki.org/wiki/Manual:Hooks/SearchAfterNoDirectMatch
https://gerrit.wikimedia.org/g/mediawiki/core/+/master/includes/search/SearchNearMatcher.php
https://doc.wikimedia.org/mediawiki-core/master/php/classSearchNearMatcher.html
That hook can't return text, you just can change the title in order to generate a match from the hook. $title has to be a Title object, if the code you posted above is the exact code you are using your exception is due to the second parameter not being one of the namespace constants like NS_MAIN
SearchAfterNoDirectMatch is used to return the title of a near-match, rather than to supplement the search results. For supplementing search results, use the onSpecialSearchResultsAppend. Here is code adds three lines to the search results:
class Hooks {
/**
* #see https://www.mediawiki.org/wiki/Manual:Hooks/SearchAfterNoDirectMatch
* #called from https://gerrit.wikimedia.org/g/mediawiki/core/+/master/includes/search/SearchNearMatcher.php
* #param $searchterm
* #param $title - array of titles
*/
public static function onSpecialSearchResultsAppend( $that, $out, $term ) {
$out->addHTML("<h3>Extra Search Results:</h3>");
$out->addHTML("<ul>");
$out->addHTML("<li>Extra Result #1</li>");
$out->addHTML("<li>Extra Result #2</li>");
$out->addHTML("<li>Extra Result #3</li>");
$out->addHTML("</ul>");
}
}
}
That should be enough to get most people going.
In Symfony2, I really like the #Security annotation to perform permissions checks.
However, when using this annotation, I come over a limitation which is you can't cumulate them.
/**
* #Security("is_granted('organizer')")
* #Security("is_granted('owner')")
*/
public function displayPlanningsAction($isModel = false)
{
or
* #Security("is_granted('subscription_valid')")
*/
class PlanningController extends CustomBaseController
{
/**
* #Security("is_granted('owner')")
*/
public function displayPlanningsAction($isModel = false)
{
the two previous will only check for is_granted('owner'). That's kind of ok in the first example because I can just put an 'and' and write this in a single line, but it's really annoying for the second example because then I have to repeat for every method of the class.
Is there a simple way I could overcome this (without using the jmsextrasecuritybundle) ?
Typescript intellisense works fine for this:
class SampleClass {
/**
* Does stuff
*
* #param blah stuff needing done
*/
public doStuff(blah: string) {
}
}
var sample = new SampleClass();
// intellisense works correctly and shows parameter description:
sample.doStuff("hello");
However switching to use the fat arrow seems to break the jsdoc intellisense (the method signature still appears, but none of the jsdoc descriptions do):
class SampleClass2 {
/**
* Does stuff
*
* #param blah stuff needing done
*/
public doStuff = (blah: string) => {
}
}
var sample2 = new SampleClass2();
// intellisense gives the method signature still but no longer picks up any of the jsdoc descriptions:
sample2.doStuff("hello");
I'm using Visual Studio 2012 Update 4; TypeScript 0.9.5.
Is this a bug, or do I need to use a different syntax for the jsdoc comments?
I'm honestly very confused why this works in the TypeScript Playground.
To have this work in Visual Studio, the function documentation needs to be on the function expression itself:
class SampleClass2 {
public doStuff =
/**
* Does stuff
*
* #param blah stuff needing done
*/
(blah: string) => {
}
}
var sample2 = new SampleClass2();
sample2.doStuff("hello");
I'm using Visual Studio 2013, so I can't test the exact set-up that you have - but you should get the type-hinting and auto-completion for either example.
Screen shot from the TypeScript playground with JSDoc...
I try to find how to let JSDoc3 automatically generate links to classes from other modules.
I find it hard to explain in words, so let me give some examples. The following script generates the expected output:
/**
* #constructor
*/
var SomeClass = function(){}
/**
* #param {SomeClass} someParam description
*/
var someFunc = function(someParam){}
That is, JSDoc3 correctly generates a link from the parameter list of someFunc to the class description of SomeClass. However, when I put SomeClass in an external module I can't seem to let JSDoc3 generate the links:
/**
* #file SomeClass.js
* #module SomeClass
*/
/**
* #constructor
*/
exports.SomeClass(){}
/**
* #file main.js
*/
var SomeClass = require('./SomeClass');
/**
* #param {SomeClass} someParam description
*/
function someFunc(someParam){}
Now JSDoc3 correctly generates the documentation for both files, but it doesn't link the parameter type of someFunc to the page of SomeClass. I tried replacing #param {SomeClass} with:
#param {SomeClass.SomeClass}
#param {SomeClass/SomeClass}
#param {#link SomeClass}
#param {#link SomeClass.SomeClass}
#param {#link SomeClass/SomeClass}
But none of these worked: in all cases the documentation simply shows the text inside the curly brackets (even when I used #link).
How can I let JSDoc3 correctly generate links to the external modules?
Use the module: prefix when referencing modules. If the module's return value is the class itself, then use module:SomeClass. If it is a property of the module, use module:SomeClass.SomeClass. The #link tag shouldn't be necessary if jsdoc can find a reference to the existing class documentation.
Use typeof import
/**
* #param {typeof import("puppeteer").Browser} browser
*/
Docs here
In C# I can make comments that start /// before the definition of a class or function and these affect the intellisense tips shown when I write code that uses the type or function. But it isn't working in Javascript. Can I get these special comments and extra tips?
Not the far, but the comment should be in the js function.
Here is an exemple :
function getArea(radius)
{
/// <summary>Determines the area of a circle that has the specified radius parameter </summary>
/// <param name="radius" type="Number">The radius of the circle.</param>
/// <returns type="Number">The area.</returns>
var areaVal;
areaVal = Math.PI * radius * radius;
return areaVal;
}
You will also find HowTo and doc in MSDN.
For VS 2017+ up to current date of this comment, you need to use JSDoc for TypeScript. "{string}" in this example means that param1 is of type string.
/**
* A description for myFunction.
* #param {string} param1 - The first argument to this function
*/
function myFunction(param1) {
...
}
JSDoc ref
MSDN
JS for VS Wiki