1. #1
    Sencha Premium Member oxymoron's Avatar
    Join Date
    Feb 2008
    Location
    South Korea
    Posts
    51
    Vote Rating
    0
    oxymoron is on a distinguished road

      0  

    Default ext-doc: ExtJS-style JavaScript comments processor

    ext-doc: ExtJS-style JavaScript comments processor


    A month ago I tried to find ExtJS-style help generator. Just to help my colleagues to be familiar with common javascript-classes I created for them with ExtJS. But I've not found anything in google... So I started my own project at google-code:

    http://code.google.com/p/ext-doc/

    It requires Java 1.6 and supports XSLT-based templates.

    But I didn't know about jsdoc-tk-ext when I started... I just tried once to use jsdoc-toolkit but I failed to generate Ext-help... Anyway, I've already started to use my help generator at work.

    Just wanted to share

    Here is example output

    Latest changes in version 1.0.104:
    • Custom tags support: If you want to add a new tag specific for your project (like @author or @version) in class description or even to method or property description you just have to declare these tags in your project-xml file:
      Code:
      <doc>
          <source>
               ...
          </source>
          <tags>
              <tag name="author" title="Author"/>
              <tag name="version" title="Class Version"/>
              <tag name="note" format="&lt;i&gt;NOTE: {0}&lt;/i&gt;"/>
          </tags>
      </doc>
      and then use it:

      Code:
      /**
       * @class SamplePackage.SampleClass
       * @extends Ext.Panel
       * This is a sample class
       * @author oxymoron
       * @version 1.0.104 
       */
    • Links to the source code from any class, method, property, etc.
      If you click on the method(class, prop..) name, you can get the exact place in the source code where this declaration made. Script syntax highlighting is done with google-code-prettify
    • Some bug fixing...

    Thanks, Marius for your suggestions.

  2. #2
    Ext User marius.ciotlos's Avatar
    Join Date
    Sep 2008
    Posts
    19
    Vote Rating
    0
    marius.ciotlos is on a distinguished road

      0  

    Thumbs up


    Quote Originally Posted by oxymoron View Post
    If you want to add a new tag specific for your project (like @author or @version) in class description or even to method or property description you just have to declare these tags in your project-xml file
    This is a very very useful feature. We were in need of custom tags and the display for them.
    Code:
    /**
    * Custom method to demonstrate custom tags
    * @author Marius
    */
    this.CustomFunction = function () {
     ...
    }
    This would put in the method box on the bottom Marius, would be nice to have author: Marius.

    To achieve this you must use a different @mauthor (method author) or something similar and in the xml file put:
    Code:
            <tag name="mauthor" format="&lt;b&gt;author:&lt;/b&gt; {0}"/>
    after this just document your methods like this:
    Code:
    /**
    * Custom method to demonstrate custom tags
    * @mauthor Marius
    */
    this.CustomFunction = function () {
     ...
    }
    Would be maybe nice to remove the format when the tag is used for a class and use it when used for property or method, this would remove the need above to have the desired format :P



    Quote Originally Posted by oxymoron
    Script syntax highlighting is done with google-code-prettify
    For some reason this did not work for all source code files.
    Code:
    tpl: new Ext.XTemplate (
                    '<tpl for=".">',
                    '<div class="x-combo-list-item"><span style="float: left">{value}</span><span style="float: right">{endtime}</span><br style="clear:both"/></div>',
                    '</tpl>'
                    ),
    The part of the code above in one of my files breaks the syntax highlight .


    My other suggestions would be:
    • A way to have custom categories (like the Events / Methods / Properties) in the class tab.
      The ones that I was thinking were:
      • Event handlers (events are click, hover or custom ones, and the handlers are the functions that are called when the events happen).
      • Callback functions (functions that are called when there is a callback from an ajax or after certain functions execute)
    • Some parameters (in the configuration xml maybe), to have a possibility to include or not the private functions in the documentation.
    • A way to use the format: &lt;a href='output/{0}.html' ext:cls='{0}'&gt;{0}&lt;/a&gt; inside custom tags and get the correct link on the class header also
    • Allow {@link PackageBase.Core.Class} inside custom tags



    If there is a need I could try to help with the Wiki pages for some documentation for the project. At least some examples and such.
    Last edited by marius.ciotlos; 15 Dec 2008 at 4:24 AM. Reason: found where custom tags where displayed so I changed a bit my post

  3. #3
    Sencha Premium Member oxymoron's Avatar
    Join Date
    Feb 2008
    Location
    South Korea
    Posts
    51
    Vote Rating
    0
    oxymoron is on a distinguished road

      0  

    Default custom tags

    custom tags


    Thanks for comments!

    Some words about custom tags. It is just first attempt to implement this thing, so it is not fixed yet. Just wanna say that I assume that there are two ways for customizing docs for your project:

    The first is changing your project-xml file (a kind of minor customization - there you just specify set of source files, declare extra tags, may be something else will be added like project name)

    And the second way is deep customization with modifying template. Currently there is only one ext template, but I'm planning to make some more (at least one "plain" template ). Template contains a description file where you can specify resources (just copied to target folder) and XSLT-templates for generating tree and class pages.

    Most difficult, but most important is class-xslt file. For example, if you want to use @author tag for class description, and also use the same tag for methods, and add it after parameters of the method, what you have to do is to change one line in class.xsl (line 182):

    Code:
    <div class="long">
      <xsl:call-template name="check-if-static"/>
      <xsl:value-of select="description/longDescr" disable-output-escaping="yes"/>
      <xsl:call-template name="method-params-details"/>
      <xsl:call-template name="custom-tags"/>
    </div>
    to this

    Code:
    <div class="long">
      <xsl:call-template name="check-if-static"/>
      <xsl:value-of select="description/longDescr" disable-output-escaping="yes"/>
      <xsl:call-template name="method-params-details"/>
      <xsl:if test="customTags"><b><xsl:value-of select="customTags/title"/></b> : <xsl:value-of select="customTags/value"/></xsl:if>
    </div>
    When ext-doc processes source file it generates internally XML that will be transformed to HTML using this XSL-transformation. It's not documented yet, but let's think that this post is the first step to ext-doc documentation

  4. #4
    Ext User marius.ciotlos's Avatar
    Join Date
    Sep 2008
    Posts
    19
    Vote Rating
    0
    marius.ciotlos is on a distinguished road

      0  

    Default


    Thanks for the feedback. I was able to adapt the code and template to include some new categories for my liking (@callback and @eventhandler).
    In my opinion a way to have this automatic (some kind of method categories) would be nice. To explain better what would be great:
    • User adds a new custom tag in myown.xml file for his project
    • User specifies this tag to be a method category
    • Ext-doc parses this new tag for processMethod and generates separate list for them (most of the time this will not be public)
    • The template to have a process for these kind of special methods to display them inside the class.xls using the title of tag for the category

    The main issues that I still have are:
    • The @private functions are always skipped, and as this is oriented mostly for all collegues here we would like to have also private functions in there with a possibility to filter them out (like for parent functions) This looks like a big task from what i've seen as now the @private / @ignore just return;
    • The search in the API Home doesn't work properly becase the store behind (in docs.js) is linked to extjs.com
      Code:
      	this.searchStore = new Ext.data.Store({
              proxy: new Ext.data.ScriptTagProxy({
                  url: 'http://extjs.com/playpen/api.php'
              }),
    • Links inside custom links {@link PackageBase.Core} or some way to use format also for the Class tags


    Appreciate all the work, and if I can help with something give me a pm.

  5. #5
    Sencha - Community Support Team jsakalos's Avatar
    Join Date
    Apr 2007
    Location
    Slovakia
    Posts
    27,133
    Vote Rating
    322
    jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future

      0  

    Default


    I've just started to play with it so take me please as a complete beginner and excuse me stupid questions...

    My idea is to generate docs from my extensions but do not include complete Ext doc to keep it simple. I'm able to generate the doc but it says "Extends Object" while it extends an Ext class in fact.

    The ideal would be to generate doc that would contain links to on-line Ext documentation. E.g. my extension extends form, docs would correctly say "Extends Ext.form.FormPanel" and that would be the link to Ext.form.FormPanel on-line doc.

    Am I only doing something wrong or such feature is not there? If the former is the case, what is the proper setup?

  6. #6
    Sencha Premium Member oxymoron's Avatar
    Join Date
    Feb 2008
    Location
    South Korea
    Posts
    51
    Vote Rating
    0
    oxymoron is on a distinguished road

      0  

    Default


    Hello, Saki!
    Initially ext-doc was made to be integrated with full ExtJS Library, and may be this use case was not considered... Unfortunatelly, I had no time for this project during last 2 months. But because of global crisis - I'll have a lot of free time soon, so I'm planning to make version 1.1, and I'll pay more attention to inheritance (and may be links to online ExtJS docs in inheritance tree will be there).

    P.S.: Thank you, I've almost forgotten to release latest 1.0 version with *.js templates and command line support )

  7. #7
    Sencha - Community Support Team jsakalos's Avatar
    Join Date
    Apr 2007
    Location
    Slovakia
    Posts
    27,133
    Vote Rating
    322
    jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future

      0  

    Default


    Thanks for info, I'm looking forward.

    I just don't get the P.S....

  8. #8
    Sencha Premium Member oxymoron's Avatar
    Join Date
    Feb 2008
    Location
    South Korea
    Posts
    51
    Vote Rating
    0
    oxymoron is on a distinguished road

      0  

    Default


    Nevermind...
    I've just remembered that in the latest version you have to specify all the JS source code files, but in the latest modifications (that I use), only "*.js" template is enough.

  9. #9
    Sencha - Community Support Team jsakalos's Avatar
    Join Date
    Apr 2007
    Location
    Slovakia
    Posts
    27,133
    Vote Rating
    322
    jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future jsakalos has a brilliant future

      0  

    Default


    Oh, I see.

    BTW, I'm able to checkout svn but I don't know how to build jar file. Well, I've build jar with (jar cf ext-doc.js extdoc) but it doesn't work. Doest it make sense to use your svn version?

  10. #10
    Sencha Premium Member oxymoron's Avatar
    Join Date
    Feb 2008
    Location
    South Korea
    Posts
    51
    Vote Rating
    0
    oxymoron is on a distinguished road

      0  

    Default


    I've uploaded latest ext-doc-1.0.128 and added build from SVN section here.

    For building from SVN just use 1.0 branch and Apache Ant.

film izle

hd film izle

film sitesi

takipci kazanma sitesi

takipci kazanma sitesi

güzel olan herşey

takipci alma sitesi

komik eğlenceli videolar