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.
> 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
fabian.jak...@1und1.de
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
qooxdoo-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qooxdoo-devel
