Closed Bug 632259 Opened 9 years ago Closed 9 years ago

Markdown in @returns clauses apparently not parsed

Categories

(Add-on SDK Graveyard :: Documentation, defect)

defect
Not set

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: adw, Assigned: wbamberg)

Details

Attachments

(1 file)

It looks like Markdown in @returns clauses isn't getting parsed.

E.g., see file.open():
https://jetpack.mozillalabs.com/sdk/1.0b2/docs/#module/api-utils/file

And apiUtils.publicConstructor():
https://jetpack.mozillalabs.com/sdk/1.0b2/docs/#module/api-utils/api-utils

Will, know what's up?

(Unrelated, but while I was trying to verify locally, I noticed that often after running cfx docs, my browser opens to http://127.0.0.1:8888/ as usual, but the page is blank except for the left sidebar, and the Developer Guide and Internals Guide links on the left are red and unclickable, and there are no lists of pages under either heading.  A race condition somewhere?)
 
> (Unrelated, but while I was trying to verify locally, I noticed that often
> after running cfx docs, my browser opens to http://127.0.0.1:8888/ as usual,
> but the page is blank except for the left sidebar, and the Developer Guide and
> Internals Guide links on the left are red and unclickable, and there are no
> lists of pages under either heading.  A race condition somewhere?)

I don't get that, but it sounds bad. How often is often? I'll try with some other systems and see if I can reproduce.
Comment on attachment 510489 [details] [diff] [review]
Run @return description through the markdown converter.

Great, thanks Will.

(In reply to comment #2)
> I don't get that, but it sounds bad. How often is often?

Most of the time.  It happened the first time I tested this patch.  A minute later I reloaded the page but the doc server had stopped for some reason.  So I ran cfx docs again and this time it worked as it should.  Today isn't the first time I've seen this happen, but it's only been recently -- maybe since the new style landed.

I saw this error in the error console after the first time:

Error: $ is not defined
Source File: http://127.0.0.1:8888/js/main.js
Line: 495

This error is the last item in the error console.  Usually I get a ton of strict warnings about all the nasty things jQuery does, but when this error occurs those warnings don't happen.  So it's as if main.js is getting evaled before jQuery is.

If it helps, my user agent string:
Mozilla/5.0 (Macintosh; Intel Mac OS X 10.5; rv:2.0b10pre) Gecko/20110113 Firefox/4.0b10pre
Attachment #510489 - Flags: review?(adw) → review+
> 
> I saw this error in the error console after the first time:
> 
> Error: $ is not defined
> Source File: http://127.0.0.1:8888/js/main.js
> Line: 495
> 
> This error is the last item in the error console.  Usually I get a ton of
> strict warnings about all the nasty things jQuery does, but when this error
> occurs those warnings don't happen.  So it's as if main.js is getting evaled
> before jQuery is.

Yes, that's exactly what it looks like. But I don't understand why it should. None of the relevant scripts are being loaded dynamically: the relevant biit of 'index.html' is:

</body>
<script src="js/jquery.js"></script>
<script src="js/showdown.js"></script>
<script src="js/render.js"></script>
<script src="js/renderapi.js"></script>
<script src="js/main.js"></script>
</html>

Can you see anything wrong there? As far as I know this should ensure that jquery is loaded before main.js.

The syntax highlighter did add a couple of new scripts which I included in <head>, but they don't depend on jQuery.

> If it helps, my user agent string:
> Mozilla/5.0 (Macintosh; Intel Mac OS X 10.5; rv:2.0b10pre) Gecko/20110113
> Firefox/4.0b10pre

Pretty similar to mine:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:2.0b10) Gecko/20100101 Firefox/4.0b10

Do you think it's worthwhile me trying the exact same version?
Assignee: nobody → wbamberg
OK, I was unable to reproduce with a new profile.  In my normal profile the pref network.http.max-persistent-connections-per-server is set to 35; when I set that pref to 35 in a new profile I can reproduce, and when I reset it to its default I can't reproduce.  My fault for modifying strange networking prefs, and for not trying a new profile sooner.

I'm sorry I led you on a wild goose chase. :\
No worries. It's a relief to know it's not broken :-).

For the sake of my education, do you know why that profile setting would cause it?

The @returns problem is submitted as: https://github.com/mozilla/addon-sdk/commit/2521ce3cab7c92b235c441df0bab033d5b68f8a7
Status: NEW → RESOLVED
Closed: 9 years ago
Resolution: --- → FIXED
I don't know, but I can make some bad guesses. :\  (I think I read about that pref on some "speed up your Firefox" site years ago when I first started using Firefox, and I've carried the same profile since then.)  It looks like 11 is the magic number to reproduce the problem.  Maybe it's related to the number of resources on the page and how many connections Firefox uses to open them.
You need to log in before you can comment on or make changes to this bug.