Links between Optic JavaScript and XQuery functions wrong

[gfurbush]

I thought I had already created this bug, but I don't see it.....

The auto-generated links between the optic JavaScript and XQuery functions (the link in the upper right on each page) are wrong. The problem is that the JavaScript version of the API is structured as prototype methods that doesn't conform to the same structure as our other JavaScript APIs.

I don't know if there's a fix that will auto-generate the links correctly, so it may make more sense to build in a way to either override and correct these links or suppress them altogether.

[dmcassel]

@gfurbush for an example, I'm looking at /AccessPlan.prototype.col. The XQuery link is /:prototype.col (with text "XQuery :prototype.col"). What should it be?

[gfurbush]

In that case, it should be "XQuery op:col"

[kcoleman-marklogic]

Oh, so all the XQuery Optic functions are in the op namespace, regardless what class they're associated with in SJS? How weird is that? Ours not to wonder why...

What does it mean for methods that appear in more than one class, like AccessPlan.prototype.explain and PreparePlan.prototype.explain? (And friends IteratePland and ModifyPlan). Are they both supposed to reference just op:explain? What SJS function is op:explain supposed to link back to, given that there are multiple candidates?

There's such a lack of symmetry between the two APIs, I kinda wonder if we should link between them at all at the function page level. Blasphemy, I know.

[gfurbush]

Oh, so all the XQuery Optic functions are in the op namespace, regardless what class they're associated with in SJS? How weird is that? Ours not to wonder why...

What does it mean for methods that appear in more than one class, like AccessPlan.prototype.explain and PreparePlan.prototype.explain? (And friends IteratePland and ModifyPlan). Are they both supposed to reference just op:explain? What SJS function is op:explain supposed to link back to, given that there are multiple candidates?

There's such a lack of symmetry between the two APIs, I kinda wonder if we should link between them at all at the function page level. Blasphemy, I know.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHubhttps://github.com//issues/624#issuecomment-261662587, or mute the threadhttps://github.com/notifications/unsubscribe-auth/ACLNFf8OF-K9gViiDJEkj_TAo-UuuGNFks5q_itQgaJpZM4K1vzG.

[gfurbush]

I’ll let Erik correct me, but my understanding is that certain methods only operate on certain objects, created upstream, while others can operate on just about any object. As for the XQuery API, how it maps to the JS API is a mystery to me.

My job is to explain how to use these APIs, not how they were implemented.

I agree that not linking between the two APIs would be fine. That’s why I offered that as an optional solution to this mess.

[dmcassel]

Okay, sounds like we need a decision on whether to solve this in code or in content (or some combination).

[gfurbush]

I'll abide by either, whatever is easiest.

The Dude abides, man.

[dmcassel]

Easiest for me is a content solution, but I have no idea how hard that is on your side. :)

[kcoleman-marklogic]

I do not believe this has a purely content-based solution. No amount of fiddling with the input can "teach" the ingest transform to magically generate (or not generate) the links, AFAIK. It has the bit between its teeth, and it is darned well gonna try.

Gordon says he'd be happy with a way to entirely suppress the linking. Say we introduce a new content attribute like apidoc:module/@link. If its value is "none", then no links are generated between the method/function pages. Neither XQuery to SJS, nor SJS to XQuery.

I had some other, more complicated, finer-grained suggestions, but this might be simplest for everyone. Have you any profund thoughts about this , @dmcassel ?

(I have no nefarious plans for other values of @link. Just leaving the door open for some weird future requirement like something one-way.)

[dmcassel]

@kcoleman-marklogic that sounds reasonable to me. Can you folks produce a zip with some link attributes for me to mess with?

[kcoleman-marklogic]

Sorry, I dropped the ball on this last week.

Do you want a whole doc zip with one or two files that contain the suggested change, or will just one modified XML file do? You can zip -u a single file into the whole hairball if you need to.

[dmcassel]

I can work with a modified XML doc.

[kcoleman-marklogic]

I'm going to email you a suitable XML file, but you might also need this commit off the docapp branch to meaningfully test it. IDK how to get that to you gracefully; my meager git fu does not stretch very far. We cannot merge the whole docapp branch to master right now (it has 9.0 specific stuff in it).

It's always possible you won't need it. I can hope, at least.

[dmcassel]

@gfurbush @kcoleman-marklogic I made a commit that respects the link="none" attribute. Has no effect if the attribute isn't there, but prevents the link from being generated if the value is none. Can you pull into docapp and test?

[kcoleman-marklogic]

I have pulled these changes on to pubs. It'll be up to @gfurbush to test them out.

[gfurbush]

Looks good.