JSDuck - the tool for documenting your Ext JS apps

[BillHubbard]

Thanks for the response. I'll try {@img} in the guide.

I figured out the multiple --image tag shortly after posting my question. The reason I set it to c:\jsduck\content is because that's the root folder, so I would specify images\image.png and guides\guide\image.png, etc., for the images. I suppose I can specify two --image options, one for c:\jsduck\images and one for c:\jsduck\guides, as long as I don't place image files directly in the guides folder, as this could potentially run the risk of two images with the same name getting copied to the same place, right?

Whenever I try to specify the --img tag, I get an error saying '< was unexpected at this time'. I've tried every permutation of specifying quotes that I could think of, even tried it without the quotes, and had no success. I want to add the title attribute to the image tag. I get the same error when I copy and paste the example you provided.

jsduck --img '<p><img src="%u" alt="%a"></p>'

One unrelated question:
For the meta-tags option, not knowing Ruby or its naming conventions, do I have to name a Ruby class file to be the same as its class name? I played briefly with a simple example and it seemed to be ignoring it, so I didn't pursue it any further.

Thanks for all your great work on this!

[renku]

as long as I don't place image files directly in the guides folder, as this could potentially run the risk of two images with the same name getting copied to the same place, right?

Right. That's again one of the things to improve.

As for the --img option, I guess Windows doesn't support single quotes, have you tried reversing the single and double quotes? You might also attempt to use the windows escape character ^, but I guess you would end up escaping way too many things.

Ruby doesn't care how your files are named, but the convention is to place SomeCoolClass into either some_cool_class.rb or somecoolclass.rb - I find the first one more readable.

[BillHubbard]

Just tried the {@img} tag in a guide, and here is the problem I face.

I now specify --images=c:\jsduck\content\images --images=c:\jsduck\content\guides, but if I do this to pick up an image from the images folder:

{@img image.png}

It creates a URL relative to where the markdown file for the guide is, so I get a broken image. Therefore, I have to specify --images=c:\jsduck\content as the root, so I can reference {@img images/image.png} in the guide. But then that doesn't work, either, because {@img} is creating a URL that is relative to where the markdown file lives (though it is odd that if I specify {@img guides/guide/image.png} it works).

I am completely unable to get an image to appear from the c:\jsduck\content\images folder from within a guide using the {@img} syntax in a guide, but it works from doc-comments. I guess that is OK if the convention is to keep all images relevant to a guide in with the guide folder, but it does make it tricky to pull up a common image.

As for the markdown syntax, I have to specify , which seems inconsistent with {@img image.png} to retrieve the same image. I get confused as to why I have to specify images/images/image.png if I simply name c:\jsduck\content\images as the root, but I don't have to specify images/guides/guide/image.png. There seems to be some logic in there somewhere muddying the water, or some concept I'm missing.

[renku]

As I told earlier, the sharing of images between doc-comments and guides doesn't work.

The Markdown syntax is a hack to overcome this limitation - you are simply referencing some image relative to the main directory of JSDuck output folder.

It's crappy, I agree.

[BillHubbard]

Turns out the problem was with the % character. I got this to work in Windows:

--img="<p><img src='%%u' alt='%%a' title='%%a'></p>"

Windows. >sigh<

And I now understand what you mean by "the sharing of images between doc-comments and guides doesn't work". I didn't fully comprehend what that meant earlier, but now I get what you're saying.

[BillHubbard]

Is there a way to display the text "{@img sample.png}" in a guide without it interpreting the tag?

[renku]

Unfortunately I haven't implemented any escaping. You might try something like:

<span>{</span>@img sample.png}

[BillHubbard]

Any idea what would cause this?

C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1304:in `unlink': Permission denied - d:/build/jsdoc/extjs/ext-all.js (Errno::EACCES)
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1304:in `remove_file'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1312:in `platform_support'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1303:in `remove_file'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1292:in `remove'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:762:in `remove_entry'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1342:in `postorder_traverse'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1342:in `postorder_traverse'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1346:in `postorder_traverse'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1341:in `postorder_traverse'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1340:in `each'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1340:in `postorder_traverse'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1341:in `postorder_traverse'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1340:in `each'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:1340:in `postorder_traverse'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:760:in `remove_entry'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:613:in `rm_r'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:609:in `each'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/1.8/fileutils.rb:609:in `rm_r'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/gems/1.8/gems/jsduck-3.0.1/lib/jsduck/app.rb:248:in `clear_output_dir'
    from C:/DOCUME~1/WHUBBA~2.SAB/LOCALS~1/Temp/ocr496.tmp/lib/ruby/gems/1.8/gems/jsduck-3.0.1/lib/jsduck/app.rb:80:in `run'

[BillHubbard]

I found the cause of the problem. The first line in the file that makes this crash had this line of code in it:

$log.level = $log.DEBUG;  //[*] DO NOT CHECK THIS IN

Not sure why that would make it die, but removing this (merely // commenting it out) allowed the doc build to succeed.

[SamuraiJack1]

Strange that nobody has asked for this before. I downgraded the required RubyGems to 1.3.5 and released JSDuck 3.0.1.

The only reason I required 1.3.7 was me having this version when I released JSDuck 0.1.

Works now, thanks a lot!