Links in code reference (and example code)

[gfwilliams]

Most of the Espruino reference page is really bad at linking through to other referenced functions. For example NRF.requestDevice may be mentioned in NRF.findDevices, but it should be a link so it can be clicked.

I recently changed the documentation builder so as long as the actual documentation contains the function/class/event's name inside single backticks, it should get automatically linked.

So, please can you flag up if:

• If you see some bit of documentation that references some other part of the Espruino API that should be linked and isn't
• Some bit of the documentation that should be in monospaced code font and isn't
• If you notice something where an example would be handy, and you have a simple example

Maybe just post up here if you find something? Or you can fix it yourself:

• Click on the ⇒ icon to the right of the affected function's heading
• It'll take you to where the documentation is in Espruino's code in GitHub
• Make sure you're signed into GitHub and click the edit icon in the top right
• Make the changes to the documentation (After the /*JSON{ .... } part you can just write code as simple Markdown). Put multiline code the three backticks ```, or just reference objects/functions/methods etc inline in a single backtick
• Issue a pull request

[MaBecker]

something like this?

url: http://www.espruino.com/Reference#ArrayBuffer

link in text:

This is the built-in JavaScript class for array buffers.
If you want to access arrays of differing types of data you may also find /Reference#DataView useful.

points to: http://www.espruino.com/DataView
result:

404 - Page Not Found.
If you don't think you should have got this message, please Contact Us and let us know so that we 
can correct the problem!

:

[gfwilliams]

Thanks - I just added a fix for this and some other ArrayBuffer docs

[opichals]

When executed in the JS console on the Reference page

This snippet:

ids = {};
for ([,n] of document.querySelectorAll('a[name]').entries()) {
    ids[n.getAttribute('name')] = n;
}

links = [];
for ([,n] of document.querySelectorAll('a[href]').entries()) {
    links.push(n.getAttribute('href'));
}

localLinks = links.filter(l => l.startsWith('#'));

localLinks.forEach(l => {
    if (!ids[l.slice(1)])
        console.log(`invalid href '${l}'`);
})

outputs the following:

invalid href '#t_l__global_Bluetooth'
invalid href '#t_l__global_I2C1'
invalid href '#t_l__global_I2C2'
invalid href '#t_l__global_I2C3'
invalid href '#t_l__global_LoopbackA'
invalid href '#t_l__global_LoopbackB'
invalid href '#t_l__global_Serial1'
invalid href '#t_l__global_Serial2'
invalid href '#t_l__global_Serial3'
invalid href '#t_l__global_Serial4'
invalid href '#t_l__global_Serial5'
invalid href '#t_l__global_Serial6'
invalid href '#t_l__global_SPI1'
invalid href '#t_l__global_SPI2'
invalid href '#t_l__global_SPI3'
invalid href '#t_l__global_Telnet'
invalid href '#t_l__global_Terminal'
invalid href '#t_l__global_USB'

[opichals]

BTW the #1498 (comment) issue seem to still be there.

[gfwilliams]

Thanks - the #1498 (comment) is still there because the docs are for 1v99, so the changes I put in aren't in those docs. If you do scripts/build_docs.py then it's fixed.

Good spot on the invalid hrefs though - just fixed that. Again though it won't take effect until the v2.00 release