17 Replies Latest reply on Jul 6, 2009 9:09 AM by Marvin Velo

    Docs folder on SWCs....

    Marvin Velo

      I notice on flex SDK 4.0.0.7219 a docs folder.

       

      How can I generate this docs for my own SWCs?

       

      Asdoc? Does it need any special parameter?

       

       

      VELO

        • 1. Re: Docs folder on SWCs....
          Gaurav J Adobe Employee

          Hi VELO,

           

          Yes, we generate the docs using asdoc. The xml files are consumed by Flash builder to show asdoc in the editor.

           

          If you run asdoc with -keep-xml=true and -skip-xsl=true, it will generate the xml files and then you will have to manually package them into the swc.

           

          For reference you can look at the build.xml for the framework project in svn trunk.

           

          It looks like:

           

              <target name="doc" depends="clean-temp-docs" description="updates framework.swc with asdoc xml">
                  <!-- Load the <asdoc> task. We can't do this at the <project> level -->
                  <!-- because targets that run before flexTasks.jar gets built would fail. -->
                  <taskdef resource="flexTasks.tasks" classpath="${FLEX_HOME}/lib/flexTasks.jar"/>

           

                  <condition property="asdoc.jvm.args" value="-Xmx384m">
                      <os family="windows"/>
                  </condition>

           

                  <condition property="asdoc.jvm.args" value="-Xmx512m">
                      <os family="mac"/>
                  </condition>

           

                  <condition property="asdoc.jvm.args" value="-Xmx512m">
                      <os family="unix"/>
                  </condition>

           


                  <!-- Call asdoc to generate dita xml files -->
                  <asdoc output="${FLEX_HOME}/tempDoc" lenient="true" failonerror="true" keep-xml="true" skip-xsl="true" fork="true">
                      <compiler.source-path path-element="${basedir}/src"/>
                      <doc-classes class="FrameworkClasses"/>
                      <doc-namespaces uri="http://www.adobe.com/2006/mxml"/>
                      <namespace uri="http://www.adobe.com/2006/mxml" manifest="${basedir}/manifest.xml"/>
                      <jvmarg line="${asdoc.jvm.args}"/>
                  </asdoc>

           

                  <!-- updates framework.swc with asdoc xml -->
                  <zip destfile="${FLEX_HOME}/frameworks/locale/en_US/framework_rb.swc" update="true">
                      <zipfileset dir="${FLEX_HOME}/tempDoc/tempdita" prefix="docs">
                          <include name="*.*"/>
                          <exclude name="ASDoc_Config.xml"/>
                          <exclude name="overviews.xml"/>
                      </zipfileset>
                  </zip>
              </target>

           

              <target name="clean-temp-docs">
                  <delete dir="${FLEX_HOME}/tempDoc" failonerror="false" includeEmptyDirs="true"/>
              </target>

           

          Thanks,

          Gaurav Jain

          Flex SDK Team

          • 2. Re: Docs folder on SWCs....
            Marvin Velo Level 1

            Thanks,

             

            I will include that on flexmojos too.

             

             

            VELO

            • 3. Re: Docs folder on SWCs....
              Marvin Velo Level 1

              BTW, what is the minimun Flex SDK version required to this feature?

               

              Is that available on 3.x series?

               

              VELO

              • 4. Re: Docs folder on SWCs....
                Gaurav J Adobe Employee

                Flex 4.

                 

                Its not in Flex 3.x

                 

                -Gaurav

                • 5. Re: Docs folder on SWCs....
                  Marvin Velo Level 1

                  Thanks for the quick anwser.

                   

                  Last question, I promisse...

                   

                  On flashbuilder I can browse the SWC classes tree.  But if I try to open the the Class.abc flashbuilder complains that source code is not found.  Is there any way to include sources on the SWC too?

                   

                   

                  VELO

                  • 6. Re: Docs folder on SWCs....
                    Gaurav J Adobe Employee

                    Not sure.

                     

                    You are getting this error for a particular swc?

                     

                    -Gaurav

                    • 7. Re: Docs folder on SWCs....
                      Marvin Velo Level 1

                      No, no error at all.  I just wanna know if there was any way to include the sources on my SWCs... Like the asdoc.

                       

                       

                      VELO

                      • 8. Re: Docs folder on SWCs....
                        Gaurav J Adobe Employee

                        No, FB doeesn't look for sources inside the swc.

                        • 9. Re: Docs folder on SWCs....
                          Marvin Velo Level 1

                          Hi,

                           

                          While I was trying to include DITA asdoc on flexmojos I got the following error:

                          Text for description in org.sonatype.flexmojos.it:AClass is not valid.

                          Saxon cannot write a DOMResult unless saxon9-dom.jar is on the classpath

                           

                          Text for description in main is not valid.

                          Saxon cannot write a DOMResult unless saxon9-dom.jar is on the classpath

                           

                          Text for description in org.sonatype.flexmojos.it.null is not valid.

                          Saxon cannot write a DOMResult unless saxon9-dom.jar is on the classpath

                           

                          Text for description in .null is not valid.

                          Saxon cannot write a DOMResult unless saxon9-dom.jar is on the classpath

                           

                          Text for description in main/aVar is not valid.

                          Saxon cannot write a DOMResult unless saxon9-dom.jar is on the classpath

                           

                          Text for description in main/main is not valid.

                          Saxon cannot write a DOMResult unless saxon9-dom.jar is on the classpath

                           

                          Any idea?  I see no saxon9-dom on flex SDK, but including it on my classpath fixed the problem.

                           

                           

                          VELO

                          • 10. Re: Docs folder on SWCs....
                            Gaurav J Adobe Employee

                            How did you try to include the DITA xmls? The SDK uses xalan.jar for transformations.

                             

                            Thanks,

                            Gaurav

                            • 11. Re: Docs folder on SWCs....
                              Marvin Velo Level 1

                              I just add "-keep-xml=true" and "-skip-xsl=true" to mine ASDoc.asdoc() invocation....

                               

                              Should xalan.jar cover saxon9-dom.jar?

                               

                              FWIW, I do rename all jars when I include they on maven environment.  Can that be related to the problem?

                              I only change the jars names.  It will be like xalan-4.0.0.7219.jar

                               

                               

                              VELO

                              • 12. Re: Docs folder on SWCs....
                                Gaurav J Adobe Employee

                                >> I do rename all jars when I include they on maven environment.  Can that be related to the problem?

                                 

                                Yes, that could be the issue. The manifest file for asdoc.jar has entry for xalan.jar

                                 

                                -Gaurav

                                • 13. Re: Docs folder on SWCs....
                                  Marvin Velo Level 1

                                  But I did include xalan.jar on classpath...  That would cover the manifest classpath....

                                   

                                  There is any coded reference to xalan.jar?

                                   

                                  VELO

                                  • 14. Re: Docs folder on SWCs....
                                    Gaurav J Adobe Employee

                                    No coded reference to xalan.

                                     

                                    btw. when you have -skip-xsl=true, saxon should not even be in the picture. It is used for xslt transformation.

                                     

                                    So there is something wrong with your classpath settings.

                                     

                                    -Gaurav

                                    • 15. Re: Docs folder on SWCs....
                                      Marvin Velo Level 1

                                      Any idea what jar could be missing?

                                       

                                      What jar does saxon9-dom role?

                                       

                                       

                                      VELO

                                      • 16. Re: Docs folder on SWCs....
                                        Gaurav J Adobe Employee

                                        The SDK does not uses saxon9-dom.jar

                                         

                                        Take a look at the manifest file inside asdoc.jar, and make sure all jars listed there are present in your classpath.

                                         

                                        -Gaurav

                                        • 17. Re: Docs folder on SWCs....
                                          Marvin Velo Level 1

                                          My classpath does include all jar files available on flex SDK lib dir...

                                           

                                           

                                          asc:jar:4.0.0.7219:compile,

                                          asdoc:jar:4.0.0.7219:compile,

                                          batik-all-flex:jar:4.0.0.7219:compile,

                                          commons-collections:jar:4.0.0.7219:compile,

                                          commons-discovery:jar:4.0.0.7219:compile,

                                          commons-logging:jar:4.0.0.7219:compile,

                                          compc:jar:4.0.0.7219:compile,

                                          copylocale:jar:4.0.0.7219:compile,

                                          digest:jar:4.0.0.7219:compile,

                                          fcsh:jar:4.0.0.7219:compile,

                                          fdb:jar:4.0.0.7219:compile,

                                          flex-compiler-oem:jar:4.0.0.7219:compile,

                                          flex-messaging-common:jar:4.0.0.7219:compile,

                                          fxgutils:jar:4.0.0.7219:compile,

                                          mxmlc:jar:4.0.0.7219:compile,

                                          optimizer:jar:4.0.0.7219:compile,

                                          saxon9:jar:4.0.0.7219:compile,

                                          swfutils:jar:4.0.0.7219:compile,

                                          velocity-dep-1.4-flex:jar:4.0.0.7219:compile,

                                          xalan:jar:4.0.0.7219:compile,

                                          xercesImpl:jar:4.0.0.7219:compile,

                                          xercesPatch:jar:4.0.0.7219:compile,

                                          xmlParserAPIs:jar:3.2.0.3958:compile,

                                           

                                          Is that a problem?