hursday, February 16, 2012 11:39 AM
To: flex-dev@incubator.apache.org
Subject: RE: asdoc comments for flash player and SDK version numbers
In this example I'd have to agree. It's more on a case by case basis for this
then. Does the comment add any value to the end user (developer) or is it j
ly not an easy nut to crack with so many classes and thousands of
lines of code to go through.
Neil
-Original Message-
From: Carol Frampton [mailto:cfram...@adobe.com]
Sent: February-16-12 12:17 PM
To: flex-dev@incubator.apache.org
Subject: Re: asdoc comments for flash player and SDK ver
Some of this code has existed a long time.
We no longer use @private except if you want to keep a public var or
method hidden from asdocs. Most people do not doc obvious private
variables or they may just use a one line // comment.
/**
* Sets the title.
*
*/
public function set title(value:Strin
On 2/16/2012 1:40 PM, Omar Gonzalez wrote:
I don't think anyone is arguing about the usefulness of code comments.
However there are a lot, and I mean a lot, of comments that are simply
noise.
Fair enough; if the comment communicates no value; I have no issues
deleting it.
All this kind of cr
On Thu, Feb 16, 2012 at 10:22 AM, Neil Madsen
wrote:
> 100% agreement here.
> Having had to just port an incredibly complex military application I wrote
> years ago I can tell you I was so happy that I took the time back then
> to write as many comments as I did in the code. I even found mysel
supposed to do.
If it ain't broke.
Just my 2 cents.
Neil
-Original Message-
From: Jeffry Houser [mailto:jef...@dot-com-it.com]
Sent: February-16-12 8:13 AM
To: flex-dev@incubator.apache.org
Cc: Omar Gonzalez
Subject: Re: asdoc comments for flash player and SDK version number
On 2/16/2012 4:01 AM, Omar Gonzalez wrote:
On Thu, Feb 16, 2012 at 12:38 AM, David Arno wrote:
On Thu, 2012-02-16 at 18:05 +1100, Justin Mclean wrote:
Hi,
Was looking though some of the framework code and noticed that a lot of
method are marked up with comments that are imported into docume
It is actually detailed, just look at the source code of UIComponent as an
exmaple, the class documentation alone is 134 lines long!! When I read the
source code I generally only look at the first lines of the documentation
to have general idea. If I need more details I read the
generated HTML doc
Well, it is not really detailed documentation. It's a documentation generated
automatically and for that you have just to follow a common procedure
for writing
the comments. It is useful so that when your code is read by other
developers, it can
be better understood.
2012/2/16 Haykel BEN JEMIA :
Personally I never write detailed documentation while developing. I
generally write a short description and the detailed documentation is
either written by someone else or in another documentation pass, which can
be done in other files.
I have suggested stub classes in an earlier e-mail because I
This is true the same time as its problematic. If we keep the
documentation in english up-to-date as
we code and the other languages get outdated then its a essential
quality issue. Also having a completely
different workflow for english than the other languages pushes a little
to ignoring the o
I am totally against stripping out the asdoc. Who do you think writes the
asdoc? We do. It is just as important as the code. If you strip it out
it won't be kept current. It should be part of any code review.
Carol
On 2/16/12 4 :15AM, "Omar Gonzalez" wrote:
>>
>> Perhaps a script to strip
On 16/02/2012 18:40, Justin Mclean wrote:
Hi,
The xml looks like a distinct possibility even if it is harder to maintain. I's
also assume that the XML skeleton was generated via some tool/script. It may
break tool tip help in Flash Builder if we went down this path.
Justin
"Big-swcs" have t
Hi,
The xml looks like a distinct possibility even if it is harder to maintain. I's
also assume that the XML skeleton was generated via some tool/script. It may
break tool tip help in Flash Builder if we went down this path.
Justin
Hi,
> I'm not quire sure what you mean. The ideal solution would be to figure out
> a way to keep comments in such a way that the during development they're
> not in our files but at release or at patch submission the proper
> documentation is there.
Yep exactly what I was suggesting. Use a script
On Thu, Feb 16, 2012 at 1:24 AM, Martin Heidegger wrote:
> On 16/02/2012 18:21, Omar Gonzalez wrote:
>
>>
>> how do they link the appropriate XML documents to the correct class and
>> methods?
>>
>> -omar
>>
> I can see that they use the signature of the methods to map the
> translation to the con
On 16/02/2012 18:21, Omar Gonzalez wrote:
how do they link the appropriate XML documents to the correct class and
methods?
-omar
I can see that they use the signature of the methods to map the translation to
the content [1].
yours
Martin.
[1]https://svn.apache.org/repos/asf/incubator/flex/w
On Thu, Feb 16, 2012 at 1:16 AM, Martin Heidegger wrote:
> The documentation for languages except english are generated using xml
> files.
> I never tried it but I guess you can use similar files for english as well
> and remove all
> the english documentation out of the sources.
>
> yours
> Marti
The documentation for languages except english are generated using xml
files.
I never tried it but I guess you can use similar files for english as
well and remove all
the english documentation out of the sources.
yours
Martin.
On 16/02/2012 18:01, Omar Gonzalez wrote:
On Thu, Feb 16, 2012 at
>
> Perhaps a script to strip out all comments and a way to create patches
> ignoring missing comments would be useful?
>
> Thanks,
> Justin
I'm not quire sure what you mean. The ideal solution would be to figure out
a way to keep comments in such a way that the during development they're
not in
This stuff is important for the docs. I'm presuming people view the docs more
than the code.
That said are Adobe committing the doc templates and task that use these?
I personally wouldn't like to see it removed unless there is a totally
different URL for the docs to go with each release (which
Hi,
> I'd really like it if we could figure out a way of getting rid of all
> that crap out of the framework as it makes reading the code far more
> difficult.
I do find it slightly annoying but I do like that it tells you what version of
the SDK etc the method requires. That's useful. It's also
What about creating stub classes for the documentation? I think this how it
is done for PHP. This could make maintenance of documentation harder though.
Haykel
On 16 February 2012 10:01, Omar Gonzalez wrote:
> On Thu, Feb 16, 2012 at 12:38 AM, David Arno wrote:
>
> > On Thu, 2012-02-16 at 1
On Thu, Feb 16, 2012 at 12:38 AM, David Arno wrote:
> On Thu, 2012-02-16 at 18:05 +1100, Justin Mclean wrote:
> > Hi,
> >
> > Was looking though some of the framework code and noticed that a lot of
> method are marked up with comments that are imported into documents re
> player version and the l
On Thu, 2012-02-16 at 18:05 +1100, Justin Mclean wrote:
> Hi,
>
> Was looking though some of the framework code and noticed that a lot of
> method are marked up with comments that are imported into documents re player
> version and the like.
>
> Here's a typical section.
> * @langversion
>
>
>
> Or do we don't bother adding this information at all and revisit at a
> later date? Anyone have a strong view on this?
>
> Thanks,
> Justin
>
>
I do think we should figure out what the proper values are to reduce the
amount of work we have to do when its time to package a release by not
hav
26 matches
Mail list logo
