JSDuck - the tool for documenting your Ext JS apps

[mono blaine]

While viewing the generated documentation, some utf-8 characters like "?,ç,?,ü,?,ö" are not displayed correctly. Actually they are displayed correctly in "source view" (files under the folder "source"), however those within the js files under "output" folder are corrupt. All my js source files are utf-8 encoded by the way.

Is there anything I should/can do to fix this?

And I must say thanks, this is a great tool

[renku]

That's interesting. I tried and UTF-8 characters displayed just fine.

Are you sure the browser is using UTF-8 encoding?

Are the files in output/ folder actually corrupt? If so, open up the file in hex editor and see how exactly the bytes have been corrupted.

Also, which OS are you using?

[mono blaine]

Yes, I've just checked and the browser is using utf-8 encoding.

In hex editor the word "dü?" is displayed as "d????" and the codes are "64 e2 94 9c e2 95 9d e2 94 80 c5 9f". I guess it is supposed to be "64 c3 bc c4 9f".

I'm using Win7 x64

Thanks

[renku]

Strange... I tried it on Windows 7, but everything seems to work just fine.

You are correct that "dü?" should be in hex "64 c3 bc c4 9f". However I'm puzzled in how you end up with this other byte sequence...

Are you using the jsduck-3.1.0.exe?

[mono blaine]

I fetch the source from github and run "gem install jsduck" and repeat this when there are updates. Let me try the exe version, maybe I did something wrong while dealing the the ruby thing.

[mono blaine]

Yeah! The exe version works perfectly. Thanks again!

[renku]

Hmm... maybe there's a difference in Ruby version. I'm using 1.8.7 (to make sure I'm backwards compatible), but you might be using 1.9.

I checked that jsduck dependencies (json, rdiscount) are upgraded to the latest version, so this shouldn't be the cause (unless you happen to have some really old version).

[mono blaine]

It appears I'm using Ruby 1.9.2 and it also appears there are some issues with encoding in version 1.9 of Ruby. I googled "ruby 1.9 encoding" and found these:

http://yehudakatz.com/2010/05/05/rub...ion-for-rails/
http://blog.grayproductions.net/arti...ault_encodings
http://peppyheppy.com/2011/1/20/ruby...ce-in-us-ascii

The reason I had this problem is definitely something about a change in Ruby 1.9, and that's all I can comprehend for the moment (never heard of Ruby till I found JSDuck )

[Zyclops]

/** 
 *  The template stores HTML that defines what will be shown on the.. bla bla
 *
 * @docauthor Alex Moore
 */
Ext.define('Template', {
    extend: 'Ext.data.Model',
    fields: [
      {name: 'id',      type: 'int'},
       // How would you document the individual fields and what their role is in the store?
      // is it a property of the model @property?
      {name: 'front',   type: 'string'},
      {name: 'back',    type: 'string'}
    ]
});

How would you document the individual fields and what their role is in the store? would you use the @property tag?

[renku]

@mono blaine: Thanks for good pointers. At one point I'll have to fix 1.9 issues.

@Zyclops: A technically correct way would indeed be to use the @property tag, but 'id', 'front', 'back' aren't properties of the Model instance itself, they are sub-properties of data property:

/**
 * @property {Object} data
 * @property {Number} data.id An ID...
 * @property {String} data.front Front...
 * @property {String} data.back Back...
 */

But this is quite clumsy way to do it. Instead I'd suggest you document them as config options (which they really are), and additionally document the class itself as extending just Object - I'd assume in this context you only are interested of the fields, all the cruft inherited from Ext.data.Model would just clutter things up:

/** 
 * @extends Object
 * The template stores HTML that defines what will be shown on the.. bla bla
 */
Ext.define('Template', {
    extend: 'Ext.data.Model',
    fields: [
      /**
       * @cfg {Number} id ...
       */
      {name: 'id',      type: 'int'},
      /**
       * @cfg {String} front ...
       */
      {name: 'front',   type: 'string'},
      /**
       * @cfg {String} back ...
       */
      {name: 'back',    type: 'string'}
    ]
});