How to document javascript callback parameters with Sphinx? - javascript

I've been using the Sphinx documentation generator to document my javascript framework, however i'm not sure how i should go about documenting the parameters my callback functions get, for example
.. js:function:: execute(event, callback)
:param object event: The event object
:param function callback: the handler
:returns: a Promise
In the previous example callback is called with a request and reply parameter, however looking at the sphinx documentation for the javascript domain does not specify how i should go about documenting this.
What's the correct way?
http://www.sphinx-doc.org/en/stable/domains.html?highlight=js%20domain#the-javascript-domain

Related

How can I find which peripheral a write callback was triggered by?

I'm making a Chrome app that involves connecting to several BLE peripherals and sending write messages simultaneously to them. I need to know when each write operation has finished on which peripheral so I can initiate more operations for that peripheral, but there doesn't seem to be a way to reference the peripheral from the callback function. The callback function is passed as a parameter to the Bluetooth API write function:
chrome.bluetoothLowEnergy.writeCharacteristicValue(string characteristicId, ArrayBuffer value, function callback)
The API shows that the READ callback function has a characteristic parameter:
function(Characteristic result) {...};
And I've then been using result.service.deviceAddress to find which device the callback is for. But the WRITE callback does not have parameters.
This gives me no way to reference the peripheral that was written to, so I can't figure out which peripheral caused this write callback to run. I can see you could do this by having a unique callback function for each of a fixed number of devices, but could someone elaborate on how to do this more dynamically using a single callback function?
I ended up adding a shared function for the callbacks (d is a Device instance):
var writeCallback = function (d) {
//...
}
Then, in my object that keeps track of the device, I added a property for a call to this function using this:
class Device {
constructor(device) {
//...
this.writeCallbackLink = (function () {
writeCallback(this);
}).bind(this);
}
}
The bind(this) is vital to make sure that this refers to the actual object and not the runtime context. Then, when I call the API function, I use the callback link:
chrome.bluetoothLowEnergy.writeCharacteristicValue(d.write.instanceId,
data_buffer, d.writeCallbackLink);
This causes writeCallback to run with the d that triggered it as a parameter.

Outlook Add-in argument exception on body.getAsync() method

According to https://dev.outlook.com/reference/add-ins/Body.html:
The GetAsync() method takes in 3 parameters. The first one is the Coercion Type which according to their documentation is a string value. The other two parameters for GetAsync are options and callback which are optional.
My code: var body = item.body.getAsync("html");
which gives this exception:
Exception details: outlook-web-16.00.js:formatted:5873 Uncaught Error: Sys.ArgumentTypeException: Object cannot be converted to the required type.
Am I not using the getAsync() method correctly? Most of the example code I've found online are using the callback parameter as well but if the options and callback parameters are optional and I only really need to get the contents of the email body as html, shouldn't this work?
P.S. This isn't an API versioning issue. I am definitely on 1.3 and body.getAsync does not return undefined.
Am I not using the getAsync() method correctly? Most of the example code I've found online are using the callback parameter as well but if the options and callback parameters are optional and I only really need to get the contents of the email body as html, shouldn't this work?
Since this method is a asynchronous, to get the result we have to use the callback. This sample should work:
Office.context.mailbox.item.body.getAsync("html", processHtmlBody);
function processHtmlBody(asyncResult) {
console.log(asyncResult.value)
}
This is a thread discussing getting the return value from asynchronous function using JavaScript.

Correct way to use Notification API without needing a callback

The Chrome Extension Notification API has a create method with the following signature:
notifications.create(string notificationId, object options, function callback)
I don't actually have a callback that I need to run when the notification finishes, but if I omit the callback, it throws an error:
Error in response to storage.get: Error: Invocation of form notifications.create(string, object, null) doesn't match definition
Fair enough. I don't write a lot of JavaScript. What's the best way to use this API when I want a noop callback?
If the API forces you to pass some function then you can just pass an empty anonymous function:
notifications.create("idHere", {options:"something"}, function() {});
Or (especially if you need to do it in multiple places) you could explicitly define your own no-op function:
function noop() {}
notifications.create("idHere", {options:"something"}, noop);
someOtherAPI.someMethod(noop);

Why does the Flickr API not let me name my own callback function for a JSONP request? Am I viewing this right?

It appears that when I use my own callback function via JSONP, Flickr wraps the JSON with its own function name called jsonFlickrFeed. And if I type the url/src directly on the browser, I do see that it's indeed wrapped.
Does this mean I'm supposed to name my function to jsonFlickrFeed? I thought when using JSONP, we get to name our own functions?
P.S. I've browsed the site for answers, but I couldn't find any direct answer. The only answer I found was that someone did use jsonFlickrFeed as the callback function name; however, being forced to use the name is what I want clarification on.
I'm also using javascript without jquery.
If you read the Flickr documentation under the callback section it says if you want to specify the callback you need to set jsoncallback to the value you want. They do not follow the pattern of "callback" like most sites use.
Callback Function
If you just want the raw JSON, with no function wrapper, add the
parameter nojsoncallback with a value of 1 to your request.
To define your own callback function name, add the parameter
jsoncallback with your desired name as the value.
nojsoncallback=1 -> {...}
jsoncallback=wooYay -> wooYay({...});
http://api.flickr.com/services/feeds/photos_public.gne?tags=cat+pic+%22&tagmode=any&format=json&jsoncallback=xxx

How to deal with response data in ajaxComplete event

Say I have this code:
function onComplete(event, request, settings)
{
// How do I get the data? In the correct format?
}
$('body').ajaxComplete(onComplete);
In regular ajax success handlers, I can just access the data directly since it will be the first parameter to the handler. It will also be in the correct format (as long as the content-type was set right on the server).
How do I deal with the data on the ajaxComplete event?
You can use it like this, but it's not documented:
function onComplete(event, request, settings) {
var data = $.httpData(request, settings.dataType, settings);
}
The jQuery.httpData function is what's used internally to get data for the success handler, but you can use it directly. Please be aware that it is undocumented, and therefore subject to change without notice in new releases. For example in jQuery 1.4.3, it will be jQuery.ajax.httpData instead.
According to the the doc:
http://api.jquery.com/ajaxComplete/
I don't think you mean to fiddle with the data, because it doesn't pass any data to the handler. If you want data you better off using the set success property in regular Ajax.
This may not be the right handler to use if you want to get data as this is really intended more as a basic notification callback (for all hooked elements) when any AJAX calls completes.
To get to your data you should you might need to be more targeted in your approach and use the $.ajax() call or one of its variants like $.get() or $.getJSON(). See here

Categories