search

jbt / docker

Documentation generator
http://jbt.github.com/docker
MIT License
233 stars 56 forks source link

Block comments vs. line comments #18

Open Prevole opened 11 years ago

Prevole commented 11 years ago

HI again,

Just a quick question to understand why the behavior of comments is not the same for line and block comments.

If I write something like that:

###
My line of description

@param {String} paramName And the parameter description
@return {Object} And the return description
###

The JSDoc like is generated in the documentation as expected, but if I write that:

# My line of description
#
# @param {String} paramName And the parameter description
# @return {Object} And the return description

The doc generated is a simple documentation without the JSDoc for @param and @return

Is it a restriction of Docker or other restriction?

jbt commented 11 years ago

The thinking behind this is that in JavaScript and other languages, the jsDoc/PHPDoc/etc. syntax is only valid for /* ... */-style block comments rather than inline // ... comments. As there's no official way of implementing jsDoc in CoffeeScript I decided to keep it as block comments do jsDoc, inline comments don't, to avoid unnecessary mess. If you think it's something important, I can have a look and see if it's possible to change.

Prevole commented 11 years ago

I understand. For me it is not so important. I was used to comment only with line comments in Coffee (maybe a bad habbits). I did not realized that the jsDoc and so follow this rule (that has some logic).

I do not want to introduce a difference in the behavior as I can take the habits to use block comments to comment my functions and classes. That's fine for me.

Thanks for your explanation.