How do I inherit documentation inside an extended class in JsDoc? - jsdoc3

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).

Related

Need to check sub class (of Class type) if it inherits from super class, using custom Detector via method visitCallExpression(UCallExpression)

I have created my own lint Detector.visitCallExpression(UCallExpression) and I need to find a way to check if a MyClass class parameter passed into a method call is a child of MyParent class?
//Example having this below code somewhere to be Lint scanned.
someObject.method(MyClass.class)
How can I determine MyClass.class inherits from MyParent class?
//Using the IntelliJ InheritanceUtil utility class
//Converts argument of MyClass.class -> psiClass
InheritanceUtil.isInheritor(psiClass, "com.somePackage.MyParent")
The PsiClass I get from the MyClass.class parameter, is resolved to the base java.lang.Class object, so the InheritanceUtil check always return false~
Anyway i found the solution
/**
* Detects if a Class<?> => PsiClass:Class<?> is a subclass of a PsiClass(?)
*
* #param type The PsiType object that is a PsiClass of the class to be checked for subclass
* #param compareToParentCanonicalClass The Class canonical name to be compared as a super/parent class
*
* #return true if the PsiType is a subclass of compareToParentCanonicalClass, false otherwise
*/
open fun isPsiTypeSubClassOfParentClassType(type: PsiType, compareToParentCanonicalClass: String): Boolean {
println("superClass checking:$type")
var psiClss = PsiTypesUtil.getPsiClass(type)
val pct = type as PsiClassType
val psiTypes: List<PsiType> = ArrayList<PsiType>(pct.resolveGenerics().substitutor.substitutionMap.values)
for (i in psiTypes.indices) {
println("canonical:"+ psiTypes[i].canonicalText)
var psiClass = psiClss?.let { JavaPsiFacade.getInstance(it.project).findClass(psiTypes[i].canonicalText, psiClss.resolveScope) }
return InheritanceUtil.isInheritor(psiClass, compareToParentCanonicalClass)
}
return false;
}

PHPDoc return type for trait function

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).

JSDOC datatype in #param

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.

Custom onNext() implementation for RxJava and Retrofit

I'm using RxJava alongside Retrofit and I'm trying to find a really clean way of abstracting my API calls in such a way that I can minimize code in the Activity.
So far, I have something like this:
Observable<SomeObservable> combined =
Observable.zip(firstObservable, secondObservable, SomeObservable::new);
// Works but needs header parsing
RxRestNetworker.performAsyncApiCall(combined, (returnData) -> {
// onNext() implementation
}, () -> hideSuggestionProgress());
The RxRestNetworker class looks like:
public class RxRestNetworker {
private static final String LOG_TAG = RxRestNetworker.class.getCanonicalName();
// Default error handling
private static Action1<Throwable> mOnError = throwable -> {
Log.e(LOG_TAG, throwable.getMessage());
throwable.printStackTrace();
};
/**
* Perform the desired request with default error handling
* #param observable
* #param onAction
* #param <T>
* #return
*/
public static <T> Subscription performAsyncApiCall(Observable<T> observable, Action1<? super T> onAction, Action0 onComplete) {
// Use default error handling
return performAsyncApiCall(observable, onAction, mOnError, onComplete);
}
/**
* Perform the desired request with some error handling OTHER than the default one
* #param observable
* #param onAction
* #param onError
* #param <T>
* #return
*/
public static <T> Subscription performAsyncApiCall(Observable<T> observable, Action1<? super T> onAction, Action1<Throwable> onError, Action0 onComplete) {
return observable.subscribeOn(Schedulers.io()).observeOn(AndroidSchedulers.mainThread())
.subscribe(onAction, onError, onComplete);
}
}
So you can see I'm using the default onError() by calling the first performAsyncApiCall method.
Now this all works, but I need to access the headers of the response by getting access to the response object.
This post claimed that I should wrap my response object and declare it like so in the API:
Observable<Response<SomeResponse>> getThings();
But I don't really care for that. It seems ugly and makes zipping observables like above a headache.
Ideally, I'd like to create an abstraction of the onNext() Action1 argument that can by default log the headers and do anything else done for every API call, then pass the results of the call back to the caller. Am I going in the wrong direction with this? Can somebody please help me find a way to abstract this in a very clean manner?
Thank you!

Find all method calls with a specific parameter type with IntelliJ

I have this code base which is rather big ( +/- 500k lines). I'm looking in it to find all the method calls that use a single parameter and that parameter is a specific type.
This means, I want to be able to find method calls like the following:
public class Foo { }
public class Bar { }
public class Doer{
public void doSomethingFoo(Foo foo) { }
public void doSomethingObject(Object object) { }
}
public class Usage {
Doer doer = new Doer();
public doSomething() {
Foo anObject = new Foo();
Bar bar = new Bar();
doer.doSomethingFoo(anObject);
doer.doSomethingObject(anObject);
doer.doSomethingObject(bar);
}
}
Since both doer.doSomethingFoo(anObject) and doer.doSomethingObject(anObject) are called, both those statements should be returned by the search. Similarly, doer.doSomethingObject(bar) is not returned. Of course, I don't know that doer exists.
I'm trying to use the Structural Search of IntelliJ to do so. I've used the following template $Instance$.$Method$($Parameter$), with the following parameters:
$Instance$ -> Text/regexp = .*
$Method$ -> Text/regexp = .*
$Parameter$ -> Text/regexp = Foo
Minimum count = 1 // Minimum one Foo parameter
Maximum count = 1 // Maximum one Foo parameter
This returns everything that has a parameter named foo (case-insensitive, apparently). So I'm probably doing something wrong here. But what? How can I get all calls to any method where the only param is of type Foo?
You are almost there. All you need to do now is set the Expression type (regexp) of $Parameter$ to Foo and leave Text/regexp blank. Additionally you may want to enable the Apply constraint within type hierarchy checkbox, to find subclasses of Foo too.
Note that you can leave the Text/regexp of all variables blank. This is equivalent to .*.