Mar 4, 2019

I love using YUIDoc for my JavaScript projects because the setup is dead simple and the default theme has everything I need, including search and good markup for SEO. It’s no secret it’s a little outdated, though (does Yahoo! even still exist?). If you’re using more modern JavaScript practices like CommonJS modules, you’ll probably run into issues with its interpretation of a “module” versus a “class”–two concepts that have evolved wildly in their practical usage in JavaScript since YUIDoc was created.

Suffice to say, “module” in YUIDoc doesn’t mean “module” in the import/export/require sense, especially when you’re splitting your code out into smaller files or using something like Browserify to bundle your project. Classes didn’t even technically exist (at least in name) until ECMAScript 2015. So how do you document a module such that it shows up nicely in your documentation?

Static vs. Constructor Classes

What you’re probably looking for is a “static class.” YUIDoc’s syntax reference notes that whenever you define a @class you should include a @static or @constructor tag. The @constructor tag’s use is self-evident in the traditional sense of a class, whereas the @static tag “indicates that you should not instantiate the class with new. You can call all of the class’s methods statically.” That sounds kind of like what we’re doing when requiring a module!

Assuming you’re exporting an object with methods, you can document the module as a static class and then write up each of its methods with the @method tag. Place a block like so at the top of your module:

Then document each of the methods of the returned object like so:

Methods indexed at same level of importance in module documentation

But what if you’re not exporting an object with methods?

Exporting a Function

If you’re exporting a single function (with or without @private methods in the module) you’ll need a workaround, though. A @class tag will not respect the usual @method tags like @param and @return.

In this case, what I recommend is placing your @class block, then immediately below it placing an @method block with the method name matching your module name. Document the function you’re returning as a normal method, then in your class block, write in the description that the class is a module that exports that method, and link to the method with an anchor tag.

This ensures that the exported function has a clear, expected name and takes a place front-and-center in your module’s documentation. Clicking the link in the class description will immediately open the documentation for your exported function.

Exported function takes a priority spot in the “class” description

Using this formatting will allow you to document any range of CommonJS modules and point clearly to your exports while ensuring they show up in the index on the left.

The future of YUIDoc

YUIDoc has been around for a while and has a lot of competitors like JSDoc, ESDoc, Doxx, Docco, Document! X, and Natural Docs. While its functionality is probably not going anywhere any time soon, I’m interested to hear what documentation tools you use and how they address modern JavaScript. Feel free to leave a comment or send me an email on this topic!

Feb 20, 2019

The Wacom Intuos is a common tablet used for creating digital artwork and vector drawings. It works surprisingly well on newer Ubuntu machines using built-in drivers and xsetwacom–perhaps even easier than on Windows, where support for the factory software can be lacking (Windows 7) or somewhat difficult to install (Windows 10).

xsetwacom scaling and multiple monitors

The Intuos will immediately begin working when plugged in; however, if the tablet input isn’t proportional to your screen or you’re using multiple monitors, you may need to tweak its resolution so the pen only maps to the right area. You can easily do this with xsetwacom, which should already be installed by default.

First, open your terminal and determine which devices you have connected. Note the ID of “Wacom Intuos S Pen stylus.”

On my machine, this command outputs the following:

Next, get the resolution of your stylus. This will output the vertices that currently map to the top left and bottom right of your screen(s).

On my machine, this tells me 0 0 15200 9500. Think of this like two points: The upper left is at 0,0, and the bottom right is at 15200,9500, or the width is 15200 and the height is 9500.

Since I have three monitors of the same size, we can ignore the Y axis–it’s already working properly. Touching the pen to the top of the pad goes to the top of the screen, and same with the bottom. The X axis isn’t how I’d like, though. With an X of 15200, currently the pointer goes all the way to the right side of the third monitor. I need to make the X of 15200 only at the far right of my first monitor. Since my monitors are the same size, this is rather simple: I just incorrectly report that the area is 3x as wide as it is, then X of 15200 becomes the far right-hand side of my first monitor.

Another way to think of this is you’re telling the tablet it’s 3x as wide as it really is. The empty spot where you’re saying there’s more tablet is mapping to the other screens. If you need help visualizing this, check out this helpful post by james00000001 on the Ubuntu MATE community. If I wanted to use the tablet on my middle monitor, I’d still make it 3x as wide, but I’d offset it by its width:

If I wanted it to map to my third monitor, the same concept applies:

If your monitors aren’t the same resolution or your input area isn’t matching up to your monitor size, you’ll have to do a little math. Hopefully you’ve brushed up on your fractions! Just remember on each axis if your cursor is going farther than you want then you need a bigger number, and vice versa.

Wacom Intuos Tablet

Inkscape input method

Even though your cursor is now showing up in the correct location, your lines in Inkscape may not. To fix this, go to Edit > Input Devices. A pane will pop out on the right with your current devices. You should see your tablet with an expander to its left. If not, make sure “Use pressure-sensitive tablet (requires restart)” is clicked below the list and restart Inkscape.

Expand your list of Wacom inputs. Click into each one and set its Mode to “Screen,” then click Save.

Inkscape Edit > Input devices…

Next, go to Edit > Preferences and find “Input Devices” under “Input/Output.” Ensure “Switch tool based on tablet device (requires restart)” is checked, then restart Inkscape.

Inkscape Edit > Preferences… > Input/Output > Input devices

Once Inkscape reloads, your lines should match up with your pen location on the screen.

Customizing the pad buttons

The buttons on your Intuos pad can be set to anything you like with a single command each. First, figure out the keystrokes you want each button to do. For my setup, I want the four buttons across the top to be “Draw Bezier curves and straight lines,” “Select and transform objects,” “Raise object,” and “Lower object.” The key combinations for each of these are Shift-F6, F1, Page Down, and Page Up. Using xsetwacom, these can be assigned with one command each.

First, get the ID of your pad from your device list again using xsetwacom --list devices. Mine is 18.

Now using one command for each button, assign a key sequence to it beginning with the word “key.” For multiple keys, leave a space between the keys.

This part can be fiddly since the button numbers don’t line up with exactly what you’d expect. The four buttons on my Intuos CTL-4100 are 1, 2, 3, and 8, and buttons 4, 5, 6, and 7 don’t exist. The reason for that is a little deeper than this article needs to go–just know that if you try to set a command on a button that isn’t there, it will tell you “Unsupported offset into ‘Wacom Button Actions’ property” and nothing bad will happen.

Jul 21, 2018

This post covers installation and usage impressions of GalliumOS on the Dell Chromebook 11 3120. To jump straight in, skip to Before You Start. Why the Chromebook? With November around the corner, I needed a decent laptop to attend National Novel Writing Month meetups. Much as I love my MSI GS73VR, a gaming laptop of […]

Continue reading...
Nov 30, 2017

To Chairman Ajit Pai and Commissioners Michael O’Rielly and Brendan Carr: This has always been a web development blog, and I’ve always followed a simple content rule:  Posts must be about a web/IoT-related project or technology. Sadly, your choices now threaten the projects I post about and the ecosystem in which they exist. Truly your […]

Continue reading...
Fork me on GitHub