jsdoc2md / dmd

The default output template for jsdoc2md
MIT License
39 stars 50 forks source link

Avoid "static class" / "static interface" / "static const" #42

Closed develar closed 7 years ago

develar commented 7 years ago

static interface or static class just add info noise — but interface cannot be static. Class also.

static const will be also rendered as const But currently instance is always specified for non-static, so, it is ok.

75lb commented 7 years ago

i agree that static interface serves no purpose but as a class is essentially a function/method, static class does make a useful distinction from instance class.

Please advise which types do not benefit from the static/instance distinction and i will fix it.

75lb commented 7 years ago

If you have your own personal style preferences, maybe use a custom partial

develar commented 7 years ago

Could you refine it so only the cases in which the "static" keyword serves no purpose are filtered out?

Yes, you are right. In case of class/interface — neither TypeScript, nor JavaScript support inner classes. But in case of static const and other cases — it should under option (for now I only add filter for class/interface, option later).

but as a class is essentially a function/method, static class does make a useful distinction from instance class

Hmm... What instance class means? Inner?

If you have your own personal style preferences

I want to improve this amazing project instead of tweaking.

develar commented 7 years ago

as a class is essentially a function/method

If you use ES6 or TypeScript — class it is class :) And cannot be inner.

75lb commented 7 years ago

If you use ES6 or TypeScript — class it is class :) And cannot be inner.

A class is a function, it can be inner, instance or static.

/**
 * something
 */
class Something {
  constructor () {
    /**
     * Inner class
     */
    const innerClass = class {}

    /**
     * Instance class
     */
    this.instanceClass = class {}
  }
}

/**
 * Static class
 */
Something.staticClass = class {}
75lb commented 7 years ago

To resolve this PR i need a list of cases in which the scope keyword ("static", "instance" etc) serves zero purpose.

develar commented 7 years ago

To resolve this PR i need a list of cases in which the scope keyword ("static", "instance" etc) serves zero purpose.

Was not aware that TS/ES6 supports nested classes. So, only interface

75lb commented 7 years ago

Hi, thanks for the edit.. I had a look and tested the PR against lots of different input cases and I need to reject this - it's still important to distinguish interfaces defined on the global scope from those packaged privately in modules. I.e., these two interfaces are different and the distinction needs to remain:

Kind: global interface Kind: inner interface of example-module

develar commented 7 years ago

My point of view restricted by strict languages like java. Your by JS. Yes... it cannot be by default. Thanks for clarification and your time.

75lb commented 7 years ago

no problem, let me know if you find anything else