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 <aha...@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" <flexcapaci...@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.
>
>
