2009/10/23 Derrell Lipman <derrell.lip...@unwireduniverse.com>:
> On Fri, Oct 23, 2009 at 11:00, Fabian Jakobs <fabian.jak...@1und1.de> wrote:
>>
>> Derrell Lipman schrieb:
>>>
>>> On Fri, Oct 23, 2009 at 10:05, Fabian Jakobs <fabian.jak...@1und1.de
>>> <mailto:fabian.jak...@1und1.de>> wrote:
>>>
>>>
>>>    I don't like the "@return {void}" lines at all. For me it is just
>>>    redundant information and visual clutter. However I see the point
>>>    of being able to decide whether it is missing because the function
>>>    doesn't return anything or whether the programmer has forgotten to
>>>    add a @return statement. For this reason I support Helder to add
>>>    functionality to the API doc generator to detect those situations
>>>    and mark them in the API viewer.
>>>
>>>
>>> Point 1: What a function returns is highly relevant information. The fact
>>> that the function returns nothing is equally relevant. Indicating such is
>>> not only not redundant, but important.
>>
>> It is important for something like an API viewer but if I have the source
>> code at hand it is redundant because the code already tells that it doesn't
>> return anything.
>
> Only if you go SEARCH the entire function to see if it returns anything.
> That was my original point.
>
>>
>>> Point 2: Adding an indication in the API viewer that an @return statement
>>> is missing does NOTHING for those of us who don't use the API viewer, but
>>> instead look at the documentation directly in the source code. We should be
>>> encouraging people to look at the source code, not discouraging. Reviewing
>>> the source code is the path to better understanding.
>>
>> Indicating it in the API viewer will help alot because this ensures that
>> at least in the framework all functions returning something are documented.
>> This is better than the situation right now because the @return statement is
>> never verified. So everyone looking at qooxdoo code can be sure that a
>> missing statement means "no return value".
>
> I agree that there should be automated mechanisms in place to ensure that
> the documentation is complete. That, however, is a separate issue from my
> point of view.

Fabian, maybe you are right. I don't see a reason why not add a return
{void} but it makes sense to not force users to do it. It's more clean
though, if we enforce to not use these unneeded comments in the code.
If one could go for sure that API documentation is always complete
this also means that when there is no documented return of a function
it should not return anything, but "void".

>>
>>> Point 3: Removing the "requirement" that all functions have an @return
>>> statement makes for an inconsistency for developers. It won't be obvious
>>> even to the initial developer that he's missing some documentation.
>>> Consistency is good. It leads to higher-quality code and documentation.
>>
>> I want only information in the API docs, which cannot be inferred
>> automatically from the code. Forcing the developer to write "useless"
>> comments will not increase the quality of the code.

Fabian, that might be a bit to strong. Especially as there might be
other things which could be inferred from the code. When you have
assertions to test parameters, when you define members with specific
types (not need for defining the type - that's easily parseable), even
things like type of return statements and exceptions are thrown are to
some degree automatically detectable. Something like this is already
partly done in the pretty-printer. The problem I see coming up here is
when to know what data is redundant. It is quite more easy to just say
that every function should define a @return - even if it's void. But
yeah, this also means a lot of comments which are basically more or
less useless. I think we need to find a good compromise here.

>
> But it is my contention that they are not "useless"; rather they are highly
> useful, and will be even more useful after an automated mechanism is put in
> palce to ensure that they are both there and accurately represented.


Not sure if they are really "highly useful". I think that they don't
hurt, but I also don't find them that useful.

>
>>>
>>> I urge you to reconsider. The extra line of documentation doesn't hurt
>>> anything, and it really does help.
>>
>> For me it hurts (a little). I have to write these lines, I have to
>> maintain them and they are taking away a little bit of my screen real
>> estate. It's nothing huge but enough for me to stop writing them. Actually
>> I've stopped writing them a long time ago and nobody seemed to bother.
>> However I'm glad you've raised the issue because right now we do handle this
>> inconsistently.
>>
>> I would like to make it a policy to not write "@return {void}" as soon as
>> the API viewer can emit warnings for missing @return statements.
>
> If I'm the only one who thinks that the @return statements should be there
> then I'll stop arguing the point and live with it. It seems, though, that
> there were a number of +1 responses to my initial request that they remain
> in place, so it seems I'm not the only one.


The +1 for me was about that I would not enforce people to not comment
them. I also would not like to remove them all, if they are already
there. I could perfectly live with a mixed usage model here.

Sebastian

>
> Derrell
>
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> qooxdoo-devel mailing list
> qooxdoo-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
>
>

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
qooxdoo-devel mailing list
qooxdoo-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel

Reply via email to