Fix jsdocs format.

[Jauhen]

All classes and method should be commented using JSDoc format:
http://usejsdoc.org/

[pukhalski]

Unfortunately I decided to move from JSDoc format to human readable style for comments (as Backbone and underscore have). I know that in this case I cannot create the API documentation as easy as I could do it with JSDoc format as well as the documentation itself should cover all the things. But I hope in this case I will have much more readable codebase. What do you think about it?

[Jauhen]

I don't agree that replacing /** * * * */ with // // // // can improve readability of comments.

[pukhalski]

It's not only about // or /* */. In my opinion JSDoc format is much more difficult to read for human being but much more easier for the machine.

But I see that it could be useful anyway. Then the compromise could lie somewhere beneath: JSDoc format + rich descriptive comments.

Thanks!

[Jauhen]

http://docs.closure-library.googlecode.com/git/closure_goog_base.js.source.html
Do you see any difficulty to read?

Bad comments, like https://github.com/epam/xframework/blob/master/xf/src/xf.router.js involve problems to read by humans, not their format.

[pukhalski]

That exactly what I was talking about — make pure JSDoc format much more descriptive. Will start working on this from xf.core.js as soon as I can. Thanks for your feedback one more time, appreciate this!

Btw, @Jauhen, do you think it will be good to have two documentation formats as well: one for API generated from JSDoc format and the second one like already exists in README file?

[Jauhen]

They are completely different types of documentations, both should exist.

[pukhalski]

Then "returning to the roots". I was struggling and trying to optimize the approach having only one type of docs (at least for now). Now I see that I was wrong and there is a need to keep both.

[nikita-leonov]

I just want to remind everyone that besides discussion it is possible to fork product and contribute into development by do an actual changes in a code :) But anyway even such involvement is very helpful.

[nikita-leonov]

Btw it is good to have at least minimalistic code conventions that explains rules to everyone in some easily readable way. For a ROAD Framework we developed such document that allows to keep such things as comments and others unified across all parts of solution - https://github.com/epam/road-ios-framework/blob/master/Documents/CodingConventions.md

I understand the point when it is closed-source project and limited amount of developers, you do not need such conventions but when you develop open source solution you likely want to have one document of such type. Do not need to outline all the rules, but some fundamental agreements like this one you can describe in document as you go, so it will grow naturally.