Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

Derrell Lipman
On Mon, Oct 19, 2009 at 05:45, <[hidden email]> wrote:
Revision: 20405
         http://qooxdoo.svn.sourceforge.net/qooxdoo/?rev=20405&view=rev
Author:   chris_schmidt
Date:     2009-10-19 09:45:48 +0000 (Mon, 19 Oct 2009)

Log Message:
-----------
[ASSIGNED - bug 2912]: Window restore method and events
http://bugzilla.qooxdoo.org/show_bug.cgi?id=2912

- removed "@return {void}" from API doc

Why? That's useful information. Don't forget that this information is not used solely by the API viewer, but also by "real people" looking at the documentation. If it doesn't say @return {something} then we have no way of knowing whether it really doesn't return anything, or if someone just forgot to add the @return documentation... which requires searching through the code to see if, in fact, there is a returned value.

I would really appreciate having @return {void} left in the documentation.

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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
Reply | Threaded
Open this post in threaded view
|

Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

Helder Magalhães

Hi everyone,



Derrell Lipman wrote:

>
>> - removed "@return {void}" from API doc
>
> Why? That's useful information. Don't forget that this information is not
> used solely by the API viewer, but also by "real people" looking at the
> documentation. If it doesn't say @return {something} then we have no way
> of
> knowing whether it really doesn't return anything, or if someone just
> forgot
> to add the @return documentation... which requires searching through the
> code to see if, in fact, there is a returned value.
>

Makes sense to me as well. I'm not sure about the current framework status
regarding the consistent application of this kind of metadata, but it helps
as-is.

Nevertheless, I'd also propose another possible approach: after removing all
of this "return void" metadada, the API viewer generator should crawl
through the methods with no documented return value in order to check if
they were coherent with code (the actual empty "return" occurrences or
variations of it) or if was simply due to missing documentation: in that
case, a documentation error (missing return value description) would be
generated. :-)

I didn't crawl for any related issue in the tracker, but this would sound
like useful. ;-)


Hope this helps,
 Helder
--
View this message in context: http://www.nabble.com/Re%3A--qooxdoo-commit--SF.net-SVN%3A-qooxdoo%3A-20405--trunk-qooxdoo-framework-source-class-qx-ui--window-Window.js-tp25959250p25971721.html
Sent from the qooxdoo-devel mailing list archive at Nabble.com.


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
Reply | Threaded
Open this post in threaded view
|

Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

Thomas Herchenroeder
In reply to this post by Derrell Lipman
+1

T.

Derrell Lipman wrote:
On Mon, Oct 19, 2009 at 05:45, <[hidden email]> wrote:
Revision: 20405
         http://qooxdoo.svn.sourceforge.net/qooxdoo/?rev=20405&view=rev
Author:   chris_schmidt
Date:     2009-10-19 09:45:48 +0000 (Mon, 19 Oct 2009)

Log Message:
-----------
[ASSIGNED - bug 2912]: Window restore method and events
http://bugzilla.qooxdoo.org/show_bug.cgi?id=2912

- removed "@return {void}" from API doc

Why? That's useful information. Don't forget that this information is not used solely by the API viewer, but also by "real people" looking at the documentation. If it doesn't say @return {something} then we have no way of knowing whether it really doesn't return anything, or if someone just forgot to add the @return documentation... which requires searching through the code to see if, in fact, there is a returned value.

I would really appreciate having @return {void} left in the documentation.

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-commit mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/qooxdoo-commit

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
Reply | Threaded
Open this post in threaded view
|

Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

Fabian Jakobs
Administrator
In reply to this post by Derrell Lipman
Derrell Lipman schrieb:

> On Fri, Oct 23, 2009 at 10:05, Fabian Jakobs <[hidden email]
> <mailto:[hidden email]>> 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.
> 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".
> 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.
> 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.

Best Fabian


--
Fabian Jakobs
JavaScript Framework Developer

1&1 Internet AG - Web Technologies
Ernst-Frey-Straße 9 · DE-76135 Karlsruhe
Telefon: +49 721 91374-6784
[hidden email]

Amtsgericht Montabaur / HRB 6484
Vorstände: Henning Ahlert, Ralph Dommermuth, Matthias Ehrlich, Thomas Gottschlich, Robert Hoffmann, Markus Huhn, Hans-Henning Kettler, Dr. Oliver Mauss, Jan Oetjen
Aufsichtsratsvorsitzender: Michael Scheeren


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
Reply | Threaded
Open this post in threaded view
|

Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

Derrell Lipman
On Fri, Oct 23, 2009 at 11:00, Fabian Jakobs <[hidden email]> wrote:
Derrell Lipman schrieb:

On Fri, Oct 23, 2009 at 10:05, Fabian Jakobs <[hidden email] <mailto:[hidden email]>> 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.

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.

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.
 
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.

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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
Reply | Threaded
Open this post in threaded view
|

Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

Sebastian Werner-2
2009/10/23 Derrell Lipman <[hidden email]>:

> On Fri, Oct 23, 2009 at 11:00, Fabian Jakobs <[hidden email]> wrote:
>>
>> Derrell Lipman schrieb:
>>>
>>> On Fri, Oct 23, 2009 at 10:05, Fabian Jakobs <[hidden email]
>>> <mailto:[hidden email]>> 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
> [hidden email]
> 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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
Reply | Threaded
Open this post in threaded view
|

Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

Derrell Lipman
On Sat, Oct 24, 2009 at 18:20, Sebastian Werner <[hidden email]> wrote:

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.

That, to me, is the worst possible situation. Then they are truly useless, as you can't count on them. In that case they're (sometimes, but not always) simply there as space fillers. Consistency IMO is the only possible solution here.

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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
Reply | Threaded
Open this post in threaded view
|

Re: [qooxdoo-commit] SF.net SVN: qooxdoo:[20405] trunk/qooxdoo/framework/source/class/qx/ui/ window/Window.js

MartinWittemann
Administrator
I have to agree with Derrell in his last point. A mixed solution would not help anybody because you can't trust the statements.
But my general opinion differs a bit. As the framework should be API complete all the time, a non existant return statement indicates implicit that nothing will be returned. So to do the work and document (and maintain) every function which returns nothing just in case that another function is not documented correct is for me a bit overhead. Especially with the possibility to check for all left out necessary return statements with the API viewer.

Best,
Martin

Derrell Lipman wrote
On Sat, Oct 24, 2009 at 18:20, Sebastian Werner <wpbasti@gmail.com> wrote:

>
> 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.
>

That, to me, is the worst possible situation. Then they are truly useless,
as you can't count on them. In that case they're (sometimes, but not always)
simply there as space fillers. Consistency IMO is the only possible solution
here.

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