1. #1
    Sencha User renku's Avatar
    Join Date
    Feb 2009
    Location
    Estonia
    Posts
    437
    Vote Rating
    17
    renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold

      0  

    Default JsDuck - an alternative documentation generator for ExtJS

    JsDuck - an alternative documentation generator for ExtJS


    Being dissatisfied with ext-doc I wrote an alternative documentation generator for ExtJS.

    * JsDuck at Github

    The highlights of JsDuck are:

    * Comments can be formatted with Markdown instead of HTML.
    * A lot more information is inferred from code - so you can keep your comments DRY.

    While doing this, JsDuck aims to be backwards-compatible with ext-doc. So comments written for ext-doc will display about the same under JsDuck, but not the other way around.

    It's still in early beta, so there's a lot of stuff in my TODO list, but I've already found it quite satisfying to use - not having to type @class and @extends at all have greatly increased my refactoring speed, and the reduced boilerplate code has made me less reluctant to create small little classes.

    Tell me what you think.

    PS. While developing it I discovered several bugs in ExtJS doc-comments. I've created a list of them for those who care to fix.
    Last edited by renku; 21 Sep 2011 at 3:51 AM. Reason: Updated link (JSDuck now part of senchalabs)
    -->

  2. #2
    Sencha - Services Team arthurakay's Avatar
    Join Date
    Sep 2008
    Location
    Antioch, IL
    Posts
    1,348
    Vote Rating
    32
    arthurakay is a jewel in the rough arthurakay is a jewel in the rough arthurakay is a jewel in the rough

      0  

    Default


    It looks like an interesting project. I'm surprised you went to so much work just to remove the HTML comments you're so frustrated with (IMO not worth the effort... then again, my documentation is very to-the-point).

    The thing I like the most about your approach is removing the XML config file - that has been a thorn in my side for a while now.

    I haven't downloaded it yet, but I'll spend some time this week playing with it.
    Arthur Kay
    Developer Relations Manager, Sencha Inc.

    Twitter | Sencha Chicago User Group
    -->

  3. #3
    Sencha - Community Support Team mschwartz's Avatar
    Join Date
    Nov 2008
    Location
    San Diego, Peoples' Republic of California
    Posts
    2,053
    Vote Rating
    17
    mschwartz will become famous soon enough mschwartz will become famous soon enough

      0  

    Default


    I like the approach, but I'm not a ruby guy and don't know Jack (SIC) about it or really want to.

    I don't understand why anyone would go to the trouble of implementing a JavaScript documentation application and not use something like Rhino (so it could document itself).
    -->

  4. #4
    Sencha User renku's Avatar
    Join Date
    Feb 2009
    Location
    Estonia
    Posts
    437
    Vote Rating
    17
    renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold

      0  

    Default


    I'm surprised you went to so much work just to remove the HTML comments you're so frustrated with (IMO not worth the effort...
    Well, it was an interesting and fun project to do. I had recently learned about recursive-descent parsing, so it was a perfect project to use some of those skills.

    I don't understand why anyone would go to the trouble of implementing a JavaScript documentation application and not use something like Rhino
    I thought about this a bit initially, but I had previously done some parsing and text-manipulation stuff in Ruby and had only good memories of it. With server-side JavaScript I had no experiences at all - so this was a bad bet for a bit larger project. Besides, I also wanted to sharpen my Ruby skills... a bit larger project was excellent choice for that. And of course, I happen to really like Ruby At the end of the day I feel it was an excellent choice.
    -->

  5. #5
    jay@moduscreate.com's Avatar
    Join Date
    Mar 2007
    Location
    Frederick MD, NYC, DC
    Posts
    16,353
    Vote Rating
    77
    jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all

      0  

    Default


    given that the sencha team is working on their own jsdoc parser, I don't see the purpose of doing this, other than going through the exercise.
    Last edited by mitchellsimoens; 14 Jul 2011 at 6:36 AM. Reason: JSDuck is part of Sencha, less confusion
    -->

  6. #6
    jay@moduscreate.com's Avatar
    Join Date
    Mar 2007
    Location
    Frederick MD, NYC, DC
    Posts
    16,353
    Vote Rating
    77
    jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all

      0  

    Default


    Quote Originally Posted by mschwartz View Post
    I like the approach, but I'm not a ruby guy and don't know Jack (SIC) about it or really want to.

    I don't understand why anyone would go to the trouble of implementing a JavaScript documentation application and not use something like Rhino (so it could document itself).

    agreed. I think the change away from HTML makes the JS documentation look cleaner, however requires users to learn markdown.
    -->

  7. #7
    Sencha User renku's Avatar
    Join Date
    Feb 2009
    Location
    Estonia
    Posts
    437
    Vote Rating
    17
    renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold

      0  

    Default


    Quote Originally Posted by jgarcia@tdg-i.com View Post
    given that the sencha team is working on their own jsdoc parser, I don't see the purpose of doing this, other than going through the exercise.
    Are you referring to ext-doc, or is there something else on the table?

    Speaking of ext-doc, I thought several times of extending it with the functionality I wanted. I studied the source code, played around with it, etc. But in the end I felt that I had to make too many changes, so maybe it was easier to just completely re-implement the whole thing. Besides, writing Java happens to cause pain for me, I opted to have fun instead with Ruby. (Sorry, the last thing is my personal problem - no offence towards Java-guys intended.)
    -->

  8. #8
    Ext JS Premium Member sumit.madan's Avatar
    Join Date
    May 2009
    Location
    Bangalore, India
    Posts
    121
    Vote Rating
    24
    sumit.madan has a spectacular aura about sumit.madan has a spectacular aura about

      0  

    Default


    I've been trying to use extdoc for a long time, but didn't like the HTML comments. JsDuck was just what I needed, thanks for your excellent work!
    -->

  9. #9
    Sencha - Community Support Team SamuraiJack1's Avatar
    Join Date
    May 2008
    Posts
    550
    Vote Rating
    3
    SamuraiJack1 will become famous soon enough

      0  

    Default


    Great, I'll definitely switch to this tool. Using Markdown instead of HTML is *soo* simpler..
    -->

  10. #10
    Sencha User renku's Avatar
    Join Date
    Feb 2009
    Location
    Estonia
    Posts
    437
    Vote Rating
    17
    renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold renku is a splendid one to behold

      0  

    Default


    I have now released another version. Almost all of ext-doc features are now implemented (only custom @tags aren't supported - and I'm unsure of how important that is).

    If somebody spots any bugs, it would be great to hear. I'm sure there are some.

    Additionally, now it would be a perfect time to ask for any extra features. I have some things in my todo-list, but it would be nice to hear some feedback.

    Hope you enjoy it. I definitely do
    -->