inch-ci / inch_ci-web

Web frontend for Inch CI
http://inch-ci.org/
MIT License
139 stars 20 forks source link

Says docs don't describe what method returns but they do #96

Closed danascheider closed 9 years ago

danascheider commented 9 years ago

Inch is saying my docs don't specify what this method returns, when the docs clearly state "#clean! returns self". I can understand it missing some less straightforward docs but since this one is quite clear I figured you might like to know about it.

Re: [B] Hash#clean! in danascheider/reactive_extensions

danascheider commented 9 years ago

I don't know why this is making all this text bold, so I'm sorry if it seems like I'm shouting!

rrrene commented 9 years ago

Hi Dana,

it seems like you are using something I would - for the lack of a better term - call "free form" in your documentation.

Unfortunately, that is Inch's weak point as it does not apply natural language processing and can't really understand what you are describing.

A pattern that Inch does understand is the one employed by TomDoc, where the last line in the docstring is a comment about the return type. It then reads something like:

# Returns a String.

What was your reasoning in choosing in this particular form of comment formatting for documentation? (And if this is actually a common form of documentation pattern that I don't know about, please point me to it - Inch can only get better that way).