In jsdoc #param,
We can write like:
/**
* #param {Object} somebody- The employee who is responsible.
*/
function sayHello(somebody: ABC) {
alert('Hello ' + somebody);
}
If I have a class like ABC and somebody is an object of type ABC, can I write it like this,?
/**
* #param {ABC} somebody- The employee who is responsible.
*/
function sayHello(somebody: ABC) {
alert('Hello ' + somebody);
}
That is, can I give my own object type inside curly braces of param rather than giving as object? Thanks in advance...
Looking at your code you are probably using TypeScript. You have 2 options:
If ABC is an object or class you can reference it by using a JSDoc namepath (ex: myNamespaceOrModule.ABC};
If ABC is not an actual JavaScript object (ex: a TypeScript interface) than you can use JSDoc #typedef tag to document a custom tag.
Please, provide the code where the ABC class is defined for a better answer.
Related
Trying to figure out how to pass some parameters to my custom implementation of TestWatcher in Junit5. The base class for all tests is set to #ExtendWith with the TestWatcher. Trying to keep it as simple as possible and I can't seem to find a straightforward answer on how to do this
I was struggling on a similar problem, basically I needed a global parameter (a separator string data) for the annotation #DisplayNameGenerator().
Because the lack of code examples of how you're trying to resolve this I'm gonna explain my approach of how to get a parameter provided by the user and see if it works for you,
I created a interface with the return of the String value that is my custom parameter that I wanted to get from the user,
#Target(ElementType.TYPE)
#Retention(RetentionPolicy.RUNTIME)
#Inherited
#API(status = EXPERIMENTAL, since = "5.4")
public #interface IndicativeSentencesSeparator {
String value();
}
So this way I could create my test with this new interface, and passing the parameter but also making it optional to use, like this,
#DisplayName("My Test")
#DisplayNameGeneration(DisplayNameGenerator.IndicativeSentencesGenerator.class)
#IndicativeSentencesSeparator(" --> ")
class MyTestClass { //Some test methods and stuff }
To get the this new class in the implementation, I used the java method class.getAnnotation(classType) in the class that you're trying to extract the value, sending by parameter the class to find, in this case the interface I created.
IndicativeSentencesSeparator separator =
myTestClass.getAnnotation(IndicativeSentencesSeparator.class);
And finally to get the parameter used the getter value,
String parameter = separator.value();
I have functions like the following in my code that return the object (for chaining):
/**
* Set properties
*
* #param $name
* #param $value
*
* #return \Boka10\Page\MenuItemConfig
*/
public function __set($name, $value)
{
$this->$name = $value;
return $this;
}
I want to move this function into a trait because, well, basically it is reused all the time.
My problem is, that the return $this line makes problems in the documentation section. In my PHPDoc it says (in this example) #return \Boka10\Page\MenuItemConfig.
How do I create a "global" trait method whose return documentation contains the correct typecast? Is it possible to do that or should I just add the __set function to each class?
I am not sure if I can explain what problem I am having here ;) What exactly would be the content of the #return tag in a globally used trait if all of these objects return their own instance?
After some digging and "hacking" I checked out the tests in Psalm and found, that the following seems to be the best method to comment these cases:
/**
* #method string somefunction($name, $value)
* #property string $name
*/
class ImplementTrait {
use MagicTrait;
}
The properties and methods are documented on the implementing class.
Note: I am using Psalm to check the code quality and this is psalms accepted way:
Psalm Tests for __call annotations
Psalm tests for __get/__set annotations
I use the following approach to add auto-completion in PHPStorm when using classes that implement some interfaces.
I create an interface with a skeleton of all target Trait public methods and extend it.
Example:
Trait MySimpleTrait {
/**
* #inheritDoc
*/
public function someMethod($someArg){
return doSomethingWithSomeArg($someArg);
}
}
Interface MySimpleTraitInterface {
/**
*
* This method do some thing with <var>$someArg</>
*
* #param mixed $someArg
* #return mixed
*/
public function someMethod($someArg);
}
interface MySimpleServiceInterface extends MySimpleTraitInterface
{
}
class MySimpleService implements MySimpleServiceInterface
{
use MySimpleTrait;
}
PHPStorm showing autocomplete for method defined in Trait:
PHPStorm showing phpDoc for method defined in Trait:
Seems absurd in 2022, but I have a lot of projects with PHP 5.6 and the syntax is supposed to be compatible (i.e., no typehint in non-scalar args or return functions).
Probably asking this wrong. Without copying the params from Foo to Bar, how do I inherit documentation of an extended class in JsDoc? When I run jsdoc from the command line, I would like to see Bar get Foos documentation (esp for the constructor).
Foo
/**
* This is Foo.
*
* #param {object} opts - Foos options.
* #param {function} opts.biz - Some callback.
*/
class Foo {
constructor(opts) {}
}
Bar
/**
* This is Bar.
*
* #extends Foo
*/
class Bar extends Foo { }
I tried inheritdoc, but it didnt seem to work (or Im doing it wrong).
I'm using thymeleaf to render my views.
Is it possible to use ' (apostrophe) as a thousands seperator?
Example: What I want is to replace WHITESPACE in the following example with a Value for an apostrophe.
<span th:text="${#numbers.formatDecimal(value, 5, 'WHITESPACE', 2, 'POINT' )}"
Is there a NumberPointType for apostrophe or another solution to achieve a formatting like this: 1'000.00
If you dig into the sourcecode of enum org.thymeleaf.util.NumberPointType you will see the only available options with standard #numbers.formatDecimal are..
public enum NumberPointType {
POINT("POINT"),
COMMA("COMMA"),
WHITESPACE("WHITESPACE"),
NONE("NONE"),
DEFAULT("DEFAULT");
...
So my preference for you is to create a custom method inside your own code, for example as a bean or a utility object, and create your own function to format the decimal as you wish.
Update
public class UIutil {
/**
* Formats a BigInteger to a thousand grouped String
* #param number
* #return
*/
public static String formatNumber (BigInteger number) {
return String.format("%,d", number);
}
}
Assign:
context.setVariable("formatter", new UIutil());
Call:
th:text="${formatter.formatNumber(value)}"
I have a method that I need to test, but ultimately I don't want this method to be public. Is there a tag I can use so that I can use the method in my tests (as if it were public) but the method will be private in the final result?
One way to do this would be to define a compiler #define value, that you set either for test code or unset otherwise:
/** #define {boolean} */
var TESTING = false;
then you can do something like this:
if (TESTING) {
var someMethodVisibleForTesting = function() {}
}
This is about your only option.