Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
On 2/8/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: > The idea of a single table that shows all the class elements, both > defined in the class and inherited, is a bit daunting. For example, the > table for the DataGrid would contain over 200 rows, probably closer to > 250 rows. I appreciate that some classes will have that many methods and properties (we are talking public ones?), and that a single table showing all elements is daunting. However, even more daunting is trying to get a birds eye view of a class, when you're an inch off the ground! That's certainly how I feel, when I look at the class summary of a class like the DataGrid. I just thought of an issue (and this may be off topic) with highly specialised classes. When a class has large family tree, the names/meanings of methods/properties of ancestor classes tend be very generic and many not make sense in the specialised decedent class. What mechanisms are in place to rename ancestor methods/properties so they make sense in the context of the decedent class. This issue is important when learning a new class that has a large family tree, because you are trying to understand what this class can do for you and generic names can slow you down. Chris -- Chris Velevitch Manager - Sydney Flash Platform Developers Group www.flashdev.org.au -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links <*> To visit your group on the web, go to: http://groups.yahoo.com/group/flexcoders/ <*> To unsubscribe from this group, send an email to: [EMAIL PROTECTED] <*> Your use of Yahoo! Groups is subject to: http://docs.yahoo.com/info/terms/
RE: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
Hi Chris, We have a few ideas on how to better show the inherited items. One idea is to show all inherited items, for example methods, in a single summary table rather than as a collection of tables that list each inherited item. The summary table would look like the summary table for the methods defined in the class itself; they would contain the method signature and the one line summary of the method. Since the table of inherited items can be quite long, we might make it collapsible so you first see the methods defined in the class, then expand the table to see inherited methods. The idea of a single table that shows all the class elements, both defined in the class and inherited, is a bit daunting. For example, the table for the DataGrid would contain over 200 rows, probably closer to 250 rows. Stephen -Original Message- From: flexcoders@yahoogroups.com [mailto:[EMAIL PROTECTED] On Behalf Of Chris Velevitch Sent: Monday, February 06, 2006 6:28 PM To: flexcoders@yahoogroups.com Subject: Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc On 2/7/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: > For your comment on issue #4, we are planning on adding the "Use" and I'm interested in knowing what your thoughts are on my comments on issue #1. > On 2/3/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: > > 1. ... We have a > > request to split the public and protected methods into separate > > tables, so that you do not see the protected methods if you are > > using the class, but view them only when you are creating a subclass. > > The distinction between using a class and subclassing a class is very > important. > > When using a class however, a single alphabetic list of all public > properties, methods, styles, effects, etc is more usable than lots of > little boxes all over the place because:- > > a. we're using THIS class and more interested seeing the behaviour and > attributes of THIS class as a whole, not the individual components > that make up the class. > > b. useful for people new to the class to help them understand what the > class can do before moving on the how the class is constructed (ie > inheritance hierarchy) or how to subclass it. > > c. show the name of the class in which it is defined next to it. > > > 3. Is it styled well? Is it easy to read and does the use of color, > > font, and layout make sense? > > No, see above. > > > 4. Are the inheritance tables usable? These are the tables that list > > the inherited items from the superclasses. > > How about a graphical inheritance hierarchy of all classes? It would > be a great way to visually see where a class fits in the whole scheme > of things. Chris -- Chris Velevitch Manager - Sydney Flash Platform Developers Group www.flashdev.org.au -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links <*> To visit your group on the web, go to: http://groups.yahoo.com/group/flexcoders/ <*> To unsubscribe from this group, send an email to: [EMAIL PROTECTED] <*> Your use of Yahoo! Groups is subject to: http://docs.yahoo.com/info/terms/
Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
On 2/7/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: > For your comment on issue #4, we are planning on adding the "Use" and I'm interested in knowing what your thoughts are on my comments on issue #1. > On 2/3/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: > > 1. ... We have a > > request to split the public and protected methods into separate > > tables, so that you do not see the protected methods if you are using > > the class, but view them only when you are creating a subclass. > > The distinction between using a class and subclassing a class is very > important. > > When using a class however, a single alphabetic list of all public > properties, methods, styles, effects, etc is more usable than lots of > little boxes all over the place because:- > > a. we're using THIS class and more interested seeing the behaviour and > attributes of THIS class as a whole, not the individual components that > make up the class. > > b. useful for people new to the class to help them understand what the > class can do before moving on the how the class is constructed (ie > inheritance hierarchy) or how to subclass it. > > c. show the name of the class in which it is defined next to it. > > > 3. Is it styled well? Is it easy to read and does the use of color, > > font, and layout make sense? > > No, see above. > > > 4. Are the inheritance tables usable? These are the tables that list > > the inherited items from the superclasses. > > How about a graphical inheritance hierarchy of all classes? It would be > a great way to visually see where a class fits in the whole scheme of > things. Chris -- Chris Velevitch Manager - Sydney Flash Platform Developers Group www.flashdev.org.au -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links <*> To visit your group on the web, go to: http://groups.yahoo.com/group/flexcoders/ <*> To unsubscribe from this group, send an email to: [EMAIL PROTECTED] <*> Your use of Yahoo! Groups is subject to: http://docs.yahoo.com/info/terms/
RE: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
Hi Chris, For your comment on issue #4, we are planning on adding the "Use" and "Tree" options to the output, which are modeled on the JavaDocs "Use" and "Tree" options. The "Tree" option will show you a class hierarchy of Flex in a text format, rather than a graphical one. Each class has a graphical inheritance tree at the top of the class description. Stephen -Original Message- From: flexcoders@yahoogroups.com [mailto:[EMAIL PROTECTED] On Behalf Of Chris Velevitch Sent: Thursday, February 02, 2006 7:16 PM To: flexcoders@yahoogroups.com Subject: Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc On 2/3/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: > 1. ... We have a > request to split the public and protected methods into separate > tables, so that you do not see the protected methods if you are using > the class, but view them only when you are creating a subclass. The distinction between using a class and subclassing a class is very important. When using a class however, a single alphabetic list of all public properties, methods, styles, effects, etc is more usable than lots of little boxes all over the place because:- a. we're using THIS class and more interested seeing the behaviour and attributes of THIS class as a whole, not the individual components that make up the class. b. useful for people new to the class to help them understand what the class can do before moving on the how the class is constructed (ie inheritance hierarchy) or how to subclass it. c. show the name of the class in which it is defined next to it. > 3. Is it styled well? Is it easy to read and does the use of color, > font, and layout make sense? No, see above. > 4. Are the inheritance tables usable? These are the tables that list > the inherited items from the superclasses. How about a graphical inheritance hierarchy of all classes? It would be a great way to visually see where a class fits in the whole scheme of things. Chris -- Chris Velevitch Manager - Sydney Flash Platform Developers Group www.flashdev.org.au -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links <*> To visit your group on the web, go to: http://groups.yahoo.com/group/flexcoders/ <*> To unsubscribe from this group, send an email to: [EMAIL PROTECTED] <*> Your use of Yahoo! Groups is subject to: http://docs.yahoo.com/info/terms/
RE: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
We use the tool internally for AS3, Flex, FlashLite, and other products. It's not ready for distribution yet, though we are working on it. Stephen -Original Message- From: flexcoders@yahoogroups.com [mailto:[EMAIL PROTECTED] On Behalf Of Jens Halm Sent: Friday, February 03, 2006 12:11 PM To: Stephen Gilson Subject: Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc > We modeled this documentation on JavaDocs. So, if you are familiar > with JavaDocs, it should look pretty familiar. You can see it here: Will there be a tool in the free release of Compiler/Framework to generate such documentation? Would be a great thing to have the same doc format used by all frameworks/tools/products throughout the whole Flash Platform. Like it is with javadoc in the Java world. Jens -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links <*> To visit your group on the web, go to: http://groups.yahoo.com/group/flexcoders/ <*> To unsubscribe from this group, send an email to: [EMAIL PROTECTED] <*> Your use of Yahoo! Groups is subject to: http://docs.yahoo.com/info/terms/
Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
> We modeled this documentation on JavaDocs. So, if you are familiar with > JavaDocs, it should look pretty familiar. You can see it here: Will there be a tool in the free release of Compiler/Framework to generate such documentation? Would be a great thing to have the same doc format used by all frameworks/tools/products throughout the whole Flash Platform. Like it is with javadoc in the Java world. Jens -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links <*> To visit your group on the web, go to: http://groups.yahoo.com/group/flexcoders/ <*> To unsubscribe from this group, send an email to: [EMAIL PROTECTED] <*> Your use of Yahoo! Groups is subject to: http://docs.yahoo.com/info/terms/
RE: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
Thanks for the feedback, For #4, we would not remove the inheritance tables, but make them look like the summary tables for the elements defined within the class. Right now, the inheritance tables are just a list of the inherited elements with no description. Instead, we could replace the lists with actual summary tables, like the list of methods defined in the class. These tables show the method signature, and contain a one-line description of the method. It would make each page much longer, so we would also need a way to show/hide the inheritance tables if we implement it. Stephen From: flexcoders@yahoogroups.com [mailto:[EMAIL PROTECTED] On Behalf Of Teoti GraphixSent: Thursday, February 02, 2006 6:14 PMTo: flexcoders@yahoogroups.comSubject: Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc 1. Would there be a way to toggle them? I develop components, so having everything is nice. But when you are making an application, yes, you definitly don't need protected stuff.2.I think it's nice, for me it's likle seeing flash cards over and over, you memorize things quicker seeing compact groups. Let's remember howmany learning styles there are out there to.3.I love it, but my opinion again. I really think for as serious of documentaion this is, it is just drab enough to catch your attention every time you read them. The style lends well to 'surfing' the classes.4. Please keep them or at least create toggles for them. They are invaluable as methioned above about memorization.I think you could ditch them if they did not serve a pratical purpose. But hey, they put the whole picture together, over and over.Great job on the docs, for me they are a pleasure to allow my self to see how kewl this stuff really is. Gets the inventive mid going!Peace, Mike On 2/2/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: All,We are looking for feedback on the Flex API documentation. Thisdocumentation is titled "Macromedia Flex 2 ActionScript and MXMLLanguage Reference" and is available from Flex Builder Help, or in astandalone form. We modeled this documentation on JavaDocs. So, if you are familiar withJavaDocs, it should look pretty familiar. You can see it here:http://livedocs.macromedia.com/labs/1/flex/langref/index.htmlAfter the Alpha release, we made several changes to it based on userfeedback. One change was to move static properties and methods to theirown area of the output. Topics for discussion now are:1. For each class, we mix both public and protected methods in the samesummary table. This is the way JavaDocs handles methods. We have arequest to split the public and protected methods into separate tables,so that you do not see the protected methods if you are using the class,but view them only when you are creating a subclass.Is this a change you would like to see?2. We include a summary of the MXML syntax for the Flex components atthe top of each class description. The syntax lists the MXML tagattributes and default values for each component.Is this helpful, or should we just remove it? Without it, you would haveto look at the tables of properties, events, effects, and styles todetermine the MXML syntax.3. Is it styled well? Is it easy to read and does the use of color,font, and layout make sense?4. Are the inheritance tables usable? These are the tables that list theinherited items from the superclasses.One possibility is to replace these inheritance lists with actualsummary tables, like you see for the properties and methods defined inthe class. The summary table shows the item, and includes a one-linesummary.Thanks,Stephen Flex Doc Team--Flexcoders Mailing ListFAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txtSearch Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service. -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service.
Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
They are just perfect! Nice work.I definitely don't agree with Gunnar's remark that:"The MXML examples at the end, however, should be removed and replaced with AS-examples."Cheers -michael On 2/3/06, gunnar a reinseth <[EMAIL PROTECTED]> wrote: 1. The docs should definately display both protected and public methods/properties - just the way it is! (and it's nice to see that the 'override' keyword is used as well)2. The MXML syntax summary is helpful to get a quick overview of the component - e.g. if i'm only looking for a style name. The MXML examples at the end, however, should be removed and replaced with AS-examples.3. No problems with the styling...4. I use the inheritance tables all the time - so, yes. --gunnarOn 2/2/06, Stephen Gilson < [EMAIL PROTECTED]> wrote: All, We are looking for feedback on the Flex API documentation. This documentation is titled "Macromedia Flex 2 ActionScript and MXML Language Reference" and is available from Flex Builder Help, or in a standalone form. We modeled this documentation on JavaDocs. So, if you are familiar with JavaDocs, it should look pretty familiar. You can see it here: http://livedocs.macromedia.com/labs/1/flex/langref/index.html After the Alpha release, we made several changes to it based on user feedback. One change was to move static properties and methods to their own area of the output. Topics for discussion now are: 1. For each class, we mix both public and protected methods in the same summary table. This is the way JavaDocs handles methods. We have a request to split the public and protected methods into separate tables, so that you do not see the protected methods if you are using the class, but view them only when you are creating a subclass. Is this a change you would like to see? 2. We include a summary of the MXML syntax for the Flex components at the top of each class description. The syntax lists the MXML tag attributes and default values for each component. Is this helpful, or should we just remove it? Without it, you would have to look at the tables of properties, events, effects, and styles to determine the MXML syntax. 3. Is it styled well? Is it easy to read and does the use of color, font, and layout make sense? 4. Are the inheritance tables usable? These are the tables that list the inherited items from the superclasses. One possibility is to replace these inheritance lists with actual summary tables, like you see for the properties and methods defined in the class. The summary table shows the item, and includes a one-line summary. Thanks, Stephen Flex Doc Team -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service . -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com SPONSORED LINKS Web site design development Computer software development Software design and development Macromedia flex Software development best practice YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service . -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service.
Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
1. The docs should definately display both protected and public methods/properties - just the way it is! (and it's nice to see that the 'override' keyword is used as well)2. The MXML syntax summary is helpful to get a quick overview of the component - e.g. if i'm only looking for a style name. The MXML examples at the end, however, should be removed and replaced with AS-examples.3. No problems with the styling...4. I use the inheritance tables all the time - so, yes. --gunnarOn 2/2/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: All, We are looking for feedback on the Flex API documentation. This documentation is titled "Macromedia Flex 2 ActionScript and MXML Language Reference" and is available from Flex Builder Help, or in a standalone form. We modeled this documentation on JavaDocs. So, if you are familiar with JavaDocs, it should look pretty familiar. You can see it here: http://livedocs.macromedia.com/labs/1/flex/langref/index.html After the Alpha release, we made several changes to it based on user feedback. One change was to move static properties and methods to their own area of the output. Topics for discussion now are: 1. For each class, we mix both public and protected methods in the same summary table. This is the way JavaDocs handles methods. We have a request to split the public and protected methods into separate tables, so that you do not see the protected methods if you are using the class, but view them only when you are creating a subclass. Is this a change you would like to see? 2. We include a summary of the MXML syntax for the Flex components at the top of each class description. The syntax lists the MXML tag attributes and default values for each component. Is this helpful, or should we just remove it? Without it, you would have to look at the tables of properties, events, effects, and styles to determine the MXML syntax. 3. Is it styled well? Is it easy to read and does the use of color, font, and layout make sense? 4. Are the inheritance tables usable? These are the tables that list the inherited items from the superclasses. One possibility is to replace these inheritance lists with actual summary tables, like you see for the properties and methods defined in the class. The summary table shows the item, and includes a one-line summary. Thanks, Stephen Flex Doc Team -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service . -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com SPONSORED LINKS Web site design development Computer software development Software design and development Macromedia flex Software development best practice YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service.
Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
On 2/3/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: > 1. ... We have a > request to split the public and protected methods into separate tables, > so that you do not see the protected methods if you are using the class, > but view them only when you are creating a subclass. The distinction between using a class and subclassing a class is very important. When using a class however, a single alphabetic list of all public properties, methods, styles, effects, etc is more usable than lots of little boxes all over the place because:- a. we're using THIS class and more interested seeing the behaviour and attributes of THIS class as a whole, not the individual components that make up the class. b. useful for people new to the class to help them understand what the class can do before moving on the how the class is constructed (ie inheritance hierarchy) or how to subclass it. c. show the name of the class in which it is defined next to it. > 3. Is it styled well? Is it easy to read and does the use of color, > font, and layout make sense? No, see above. > 4. Are the inheritance tables usable? These are the tables that list the > inherited items from the superclasses. How about a graphical inheritance hierarchy of all classes? It would be a great way to visually see where a class fits in the whole scheme of things. Chris -- Chris Velevitch Manager - Sydney Flash Platform Developers Group www.flashdev.org.au -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links <*> To visit your group on the web, go to: http://groups.yahoo.com/group/flexcoders/ <*> To unsubscribe from this group, send an email to: [EMAIL PROTECTED] <*> Your use of Yahoo! Groups is subject to: http://docs.yahoo.com/info/terms/
Re: [flexcoders] Flex 2 - Looking for feedback on Flex API doc
1. Would there be a way to toggle them? I develop components, so having everything is nice. But when you are making an application, yes, you definitly don't need protected stuff. 2.I think it's nice, for me it's likle seeing flash cards over and over, you memorize things quicker seeing compact groups. Let's remember howmany learning styles there are out there to. 3.I love it, but my opinion again. I really think for as serious of documentaion this is, it is just drab enough to catch your attention every time you read them. The style lends well to 'surfing' the classes. 4. Please keep them or at least create toggles for them. They are invaluable as methioned above about memorization. I think you could ditch them if they did not serve a pratical purpose. But hey, they put the whole picture together, over and over. Great job on the docs, for me they are a pleasure to allow my self to see how kewl this stuff really is. Gets the inventive mid going! Peace, Mike On 2/2/06, Stephen Gilson <[EMAIL PROTECTED]> wrote: All, We are looking for feedback on the Flex API documentation. This documentation is titled "Macromedia Flex 2 ActionScript and MXML Language Reference" and is available from Flex Builder Help, or in a standalone form. We modeled this documentation on JavaDocs. So, if you are familiar with JavaDocs, it should look pretty familiar. You can see it here: http://livedocs.macromedia.com/labs/1/flex/langref/index.html After the Alpha release, we made several changes to it based on user feedback. One change was to move static properties and methods to their own area of the output. Topics for discussion now are: 1. For each class, we mix both public and protected methods in the same summary table. This is the way JavaDocs handles methods. We have a request to split the public and protected methods into separate tables, so that you do not see the protected methods if you are using the class, but view them only when you are creating a subclass. Is this a change you would like to see? 2. We include a summary of the MXML syntax for the Flex components at the top of each class description. The syntax lists the MXML tag attributes and default values for each component. Is this helpful, or should we just remove it? Without it, you would have to look at the tables of properties, events, effects, and styles to determine the MXML syntax. 3. Is it styled well? Is it easy to read and does the use of color, font, and layout make sense? 4. Are the inheritance tables usable? These are the tables that list the inherited items from the superclasses. One possibility is to replace these inheritance lists with actual summary tables, like you see for the properties and methods defined in the class. The summary table shows the item, and includes a one-line summary. Thanks, Stephen Flex Doc Team -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service. -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com SPONSORED LINKS Web site design development Computer software development Software design and development Macromedia flex Software development best practice YAHOO! GROUPS LINKS Visit your group "flexcoders" on the web. To unsubscribe from this group, send an email to: [EMAIL PROTECTED] Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service.
[flexcoders] Flex 2 - Looking for feedback on Flex API doc
All, We are looking for feedback on the Flex API documentation. This documentation is titled "Macromedia Flex 2 ActionScript and MXML Language Reference" and is available from Flex Builder Help, or in a standalone form. We modeled this documentation on JavaDocs. So, if you are familiar with JavaDocs, it should look pretty familiar. You can see it here: http://livedocs.macromedia.com/labs/1/flex/langref/index.html After the Alpha release, we made several changes to it based on user feedback. One change was to move static properties and methods to their own area of the output. Topics for discussion now are: 1. For each class, we mix both public and protected methods in the same summary table. This is the way JavaDocs handles methods. We have a request to split the public and protected methods into separate tables, so that you do not see the protected methods if you are using the class, but view them only when you are creating a subclass. Is this a change you would like to see? 2. We include a summary of the MXML syntax for the Flex components at the top of each class description. The syntax lists the MXML tag attributes and default values for each component. Is this helpful, or should we just remove it? Without it, you would have to look at the tables of properties, events, effects, and styles to determine the MXML syntax. 3. Is it styled well? Is it easy to read and does the use of color, font, and layout make sense? 4. Are the inheritance tables usable? These are the tables that list the inherited items from the superclasses. One possibility is to replace these inheritance lists with actual summary tables, like you see for the properties and methods defined in the class. The summary table shows the item, and includes a one-line summary. Thanks, Stephen Flex Doc Team -- Flexcoders Mailing List FAQ: http://groups.yahoo.com/group/flexcoders/files/flexcodersFAQ.txt Search Archives: http://www.mail-archive.com/flexcoders%40yahoogroups.com Yahoo! Groups Links <*> To visit your group on the web, go to: http://groups.yahoo.com/group/flexcoders/ <*> To unsubscribe from this group, send an email to: [EMAIL PROTECTED] <*> Your use of Yahoo! Groups is subject to: http://docs.yahoo.com/info/terms/
