Move to doctrine instead of jsd

[skad0]

JSD is just hard to support. And I see no sense to continue using it.

Plus as I see in bem-core, there no usage of custom properties (like @bem etc.) (if we really need them, maybe we should just implement doctrine plugin, but for who?).

@tadatuta @veged

[veged]

But how you suggest to handle i-bem.js declarations which are implemented here https://github.com/bem/jsd-plugins-bem/blob/master/plugins/bem.js?

[skad0]

@veged I just haven't found there usages, can you show?

[veged]

this plugin provide an ability to get @bem implicit from decl call (see https://github.com/bem/jsd-plugins-bem/blob/master/plugins/bem.js#L80)

[skad0]

Why we can't do this just the same without custom json parser? For example, in external package or even as a part of implementation some documenting tools. If we really need, we also can create plugin for jsdoc.

I don't understand why we must support the whole jsdoc parser for this "feature".

[veged]

1. There is no "custom JSON parser" — it's just esprima enriched with comments (which are not in AST standard): https://github.com/bem/jsd/blob/master/lib/parser.js#L1
2. Of course, we can reimplement such functionality in almost any other pluggable tool — but why we need to do this?
3. What did you mean in terms "support"? What changes are we need to do?

[skad0]

What did you mean in terms "support"? What changes are we need to do?

We have plugins only for few jsdoc features. For example, we don't support even @throws.
We don't support such things as @constructs and use @constructor(which is equal to @class) instead and even in such case we do it wrong. Described here.

I didn't really check, but i think there are more cases when we are doing wrong.

but why we need to do this

To avoid creating and supporting jsdoc standard by ourselves and make us to use all jsdoc features just in time.

There is no "custom JSON parser" — it's just esprima enriched with comments

Yes, but again, we support limited and somewhere wrong jsdoc standard. Why we need this?

[qfox]

Why doctrine?

[veged]

For example, we don't support even @throws.

We don't use it either ;-) It's true — we only implement a subset of JSDoc based on real usage.

We don't support such things as @constructs and use @constructor (which is equal to @Class)

Actually, we intentionally use @constructor since it's more suitable for semantic we try to express.

I didn't really check, but i think there are more cases when we are doing wrong.

How about the presumption of innocence? ;-)

Yes, but again, we support limited and somewhere wrong jsdoc standard. Why we need this?

We implement jsd with a heavy heart and in the absence of any good tools — probably now there is some new tools wich is better than before, but honestly, I'm not sure that support of couple tags in jsd (for example https://github.com/bem/jsd-plugins-bem/blob/master/plugins/event.js) will be more energy spending than migration to a new tool.

[skad0]

Actually, we intentionally use @constructor since it's more suitable for semantic we try to express.

But it is the violation of the common usage fixed in the documentation o_O

We don't use it either ;-)

currently, we use it ;-)

more energy spending than migration to a new tool.

here i really can agree with you, but still there is a question. If I find some error, violations etc.(for example couple of error in building bem-core which exists for a pretty long period of time) and create issues, are there anybody who want to maintain packages? If yes - its ok. If no - i don't know what to do.

[qfox]

We don't use it either ;-)

We also use it covertly in islands in debug mode via asserts. ;-)

[veged]

let's formulate concrete issues for jsd and make a pair-programming meeting with me to do them