[Discussion] Remove ExcludeClass from classes in the SDK

[jude <fl...@gmail.com>]

For discussion, I think we should remove the [ExcludeClass] from all the
classes in the SDK. The reasons are mainly that I've found really useful
classes usually after the fact that were excluded from auto complete and
documentation. The reasons for ExcludeClass seem to be to make auto
complete faster and remove classes that were deemed not to be important to
developers. I've never had an issue with auto complete being slow and the
last time I was paying attention to what showed in auto complete in AS3 as
I typed was after the first month of use. That is, I don't notice the
classes I'm not looking for as I type but I do notice classes that I find
useful. So if these classes showed up in auto complete it would be *more*
beneficial as I will notice them when I need them and not notice them when
I don't.

Another reason to remove ExcludeClass is there are cases that these classes
do not show up in MXML using the mxmlc or in AS3 projects where they will
be used. This causes the compiler to complain and in some cases the app
can't be compiled. Now that everyone agrees we should take a vote.

Re: [Discussion] Remove ExcludeClass from classes in the SDK

[Alex Harui <ah...@adobe.com>]

On 8/17/14 4:04 PM, "jude" <fl...@gmail.com> wrote:

>Thanks for the clarification. I forgot about backward compatibility. As
>for
>code complete, in the Design Extensions Readme Kit.txt I found this
>reference:
>
>PicnicExtensions
This part is specific to design extensions.  If a TextInput is proxied by
a DesignViewTextInput class that is only used to present the TextInput in
DesignView and not designed to be used in other applications, I would
argue that DesignViewTextInput should have ExcludeClass so it doesn't
clutter up the choices in auto-complete.  Or, in reality, that the ASDOc
and IDEs would allow filtering of classes with particular attributes so
you could get documentation on DesignViewTextInput when the time comes to
try to fix a bug in it.

>
>
>I don't think that documenting means all these other things. I think once
>you know it exists you have the possibility of breaking things when the
>class is updated or changed or causing interdependency because for me and
>another dev recently are using MediaQueryImporter already all that
>ExcludeClass has done was hide it from some highly visible locations.
MediaQueryParser is a separate case.  Maybe we should add it to the
documentation.  I think it had ExcludeClass at Adobe because it wasn't
really using MediaQuery-compliant CSS tags, so why document it and invite
folks to try it only to their disappointment?

>
>
>I'm trying to get a list of classes that have ExcludeClass in them so we
>can compare. I know that working on the TLF SDK there were way too many
>classes that had ExcludeClass and the compiler would complain until I
>removed that tag. 
I haven't had problems with ExcludeClass and the compiler.  Not sure why
you are.  But again, are you sure you love the APIs in TLF enough to bake
more of them "forever"?  Like Parcels and all other stuff that was hard to
understand?

Again, I probably won't veto any individual changes, but I would caution
against an automatic removal of all ExcludeClass metadata.

-Alex

Re: [Discussion] Remove ExcludeClass from classes in the SDK

[jude <fl...@gmail.com>]

Thanks for the clarification. I forgot about backward compatibility. As for
code complete, in the Design Extensions Readme Kit.txt I found this
reference:

PicnicExtensions

    This is a Flex Library project that defines the design view extension
classes
    for the picnic components. Note that the DesignExtensions and Picnic
projects
    are on the Library Path of this project.

    Many IComponentExtension functions are implemented by one or more of
these extension classes.
    All class definitions are preceded with an [ExcludeClass] metadata tag
so that the class is
    not included in code hints. This way, client projects that use the
Picnic classes will not
    receive code hints for these design extension classes.

    The design.xml file in the Picnic project sets up the associations
between the
    Picnic components and the corresponding design extension class in this
project.


I don't think that documenting means all these other things. I think once
you know it exists you have the possibility of breaking things when the
class is updated or changed or causing interdependency because for me and
another dev recently are using MediaQueryImporter already all that
ExcludeClass has done was hide it from some highly visible locations. It is
still found when you come across it in the SDK files (or through Spotlight)
or Open Type ( CMD + SHIFT + T ). Once you know it exists, you can start
using it. It's not quite the same as private which prevents you from using
it unless you modify the SDK. I think it's closer to mx_internal but not as
tricksy (as gollum would say). You don't have to declare a namespace or do
anything special except know it's name.

I'm trying to get a list of classes that have ExcludeClass in them so we
can compare. I know that working on the TLF SDK there were way too many
classes that had ExcludeClass and the compiler would complain until I
removed that tag. It seemed more like it was used because the class had
very little comments. I think as developers it's OK to see classes that may
not be fully documented. Before, when the SDK was under Adobe's umbrella it
made sense but now, if we see a class that is not fully baked or has few
comments or documentation we can do something about it. My 2 cents



On Sun, Aug 17, 2014 at 12:07 AM, Alex Harui <ah...@adobe.com> wrote:

> Interesting.  I'd never heard of auto-complete as a reason to use
> ExcludeClass.  Size of documentation is a concern, but the main issue,
> IMO, regarding private, @private, mx_internal and/or ExcludeClass is about
> backward-compatibility.  Once you document it, you can't go changing it
> without fear of breaking someone's code.  So, you'd better be pretty happy
> with the API names that you want to document, and probably should make
> sure the API doesn't create a tangled nest of dependencies.
>
> So, I'd argue that you shouldn't remove every ExcludeClass or make every
> private method public.  But if any committer finds something useful and
> worth documenting, then we should think about the backward-compatibility
> impact and make the change unless there will be serious repercussions.
>
> -Alex
>
> On 8/16/14 2:29 PM, "jude" <fl...@gmail.com> wrote:
>
> >For discussion, I think we should remove the [ExcludeClass] from all the
> >classes in the SDK. The reasons are mainly that I've found really useful
> >classes usually after the fact that were excluded from auto complete and
> >documentation. The reasons for ExcludeClass seem to be to make auto
> >complete faster and remove classes that were deemed not to be important to
> >developers. I've never had an issue with auto complete being slow and the
> >last time I was paying attention to what showed in auto complete in AS3 as
> >I typed was after the first month of use. That is, I don't notice the
> >classes I'm not looking for as I type but I do notice classes that I find
> >useful. So if these classes showed up in auto complete it would be *more*
> >beneficial as I will notice them when I need them and not notice them when
> >I don't.
> >
> >Another reason to remove ExcludeClass is there are cases that these
> >classes
> >do not show up in MXML using the mxmlc or in AS3 projects where they will
> >be used. This causes the compiler to complain and in some cases the app
> >can't be compiled. Now that everyone agrees we should take a vote.
>
>

Re: [Discussion] Remove ExcludeClass from classes in the SDK

[Alex Harui <ah...@adobe.com>]

Interesting.  I'd never heard of auto-complete as a reason to use
ExcludeClass.  Size of documentation is a concern, but the main issue,
IMO, regarding private, @private, mx_internal and/or ExcludeClass is about
backward-compatibility.  Once you document it, you can't go changing it
without fear of breaking someone's code.  So, you'd better be pretty happy
with the API names that you want to document, and probably should make
sure the API doesn't create a tangled nest of dependencies.

So, I'd argue that you shouldn't remove every ExcludeClass or make every
private method public.  But if any committer finds something useful and
worth documenting, then we should think about the backward-compatibility
impact and make the change unless there will be serious repercussions.

-Alex

On 8/16/14 2:29 PM, "jude" <fl...@gmail.com> wrote:

>For discussion, I think we should remove the [ExcludeClass] from all the
>classes in the SDK. The reasons are mainly that I've found really useful
>classes usually after the fact that were excluded from auto complete and
>documentation. The reasons for ExcludeClass seem to be to make auto
>complete faster and remove classes that were deemed not to be important to
>developers. I've never had an issue with auto complete being slow and the
>last time I was paying attention to what showed in auto complete in AS3 as
>I typed was after the first month of use. That is, I don't notice the
>classes I'm not looking for as I type but I do notice classes that I find
>useful. So if these classes showed up in auto complete it would be *more*
>beneficial as I will notice them when I need them and not notice them when
>I don't.
>
>Another reason to remove ExcludeClass is there are cases that these
>classes
>do not show up in MXML using the mxmlc or in AS3 projects where they will
>be used. This causes the compiler to complain and in some cases the app
>can't be compiled. Now that everyone agrees we should take a vote.