Doc comments

[kvokka]

Solving the doc comments problem, I found a lot of interesting stuff into configuration.
At the current moment, plugin valid-jsdoc if activated, but it is very close from throwing the exception, because it require @return line for every function, which returns something. Also, plugin lines-around-comment if switched off, while really we want to have empty space before & after a block comment, plus we do not check the comment content (I mean, that reviewer have to check the ending period manually, at least).

I solved almost all this misconceptions (in the fork), but I still have something to discuss:

1. 'lines-around-comment/afterBlockComment' will conflict with require-jsdoc. So it is the only unsolved problem, but at the current moment i did not found the solution
2. We can go in the different direction and use embedded eslint module valid-esdoc, but this module will require @return line, at least, if the function have explicit return. I see this solution much cleaner + it will make the documenting process cleaner + swagger or any other tool can easily snach it. But it will require to add this return on all projects after the update (and keep adding them after).

Anyway, now I understand the problem much better. So, if u want, i can move in one of selected direction or discuss any other way.

Option drop this idea is applicable also. This topic is just a suggestion.

cc @nunorafaelrocha