What I find myself wanting often is to “link” different pieces of code together, in a way that lets me easily navigate between them, and that also binds them all together with an explanation. IDE features like “show references” etc only go so far - not everything in the codebase that’s connected is connected via the type system. What I’m imagining is something like “Roam for code comments”, where you can add a tag and a comment to a piece of code, and the same tag to another piece of code, and maybe a third one, and they’re automatically connected.

If you click on a tag you jump to a page for that particular tag which shows you all the comments for that tag, and maybe a few lines of code for each one. You can click on a comment to jump to that file.

One comment can link to more than one tag.

The code

This first piece is the “definition” of the tag. Note the colon after the tag name:

// ##autoRunInTabletMode:
// In tablet mode, top-level list screens auto-push their first item detail
// screen so that the detail screen is always present, unless the list is
// empty.  This flag, then, is only true for actions which push detail
// screens.
//
// FIXME: Composite actions right now don't auto-run, though arguably they
// should if one of their constituent actions want to.

public get autoRunInTabletMode(): boolean {
    return false;
}

These two comments add to the tag:

// We don't want to auto-push in the builder, however, because if we did we
// couldn't tell whether the app creator wants to edit the detail screen or
// the list screen.  This ##autoRunInTabletMode flag here is used by item
// renderers to decide whether they should auto-run their actions if they're
// the first item.

return { onClick, targetURL, autoRunInTabletMode: !env.appEnvironment.isBuilder && action.autoRunInTabletMode };

// The map screen doesn't have list items, so it doesn't use the regular
// ##autoRunInTabletMode flag.
const shouldPush =
    renderEnvironment.sizeClass === "tablet" &&
    renderEnvironment.displayContext === "master" &&
    !renderEnvironment.appEnvironment.isBuilder &&
    this.state.selectedMarker === undefined &&
    this.state.lastMarker === undefined &&
    markers.length > 0;
if (shouldPush) {
    this.onMarkerSelected(markers[0]);
}

The result

This is the information I’d like to see on the page for that tag:

##autoRunInTabletMode

types.ts

In tablet mode, top-level list screens auto-push their first item detail screen so that the detail screen is always present, unless the list is empty. This flag, then, is only true for actions which push detail screens.

FIXME: Composite actions right now don't auto-run, though arguably they should if one of their constituent actions want to.

public get autoRunInTabletMode(): boolean {
    return false;
}

Here's another one:

{}

components.tsx

We don't want to auto-push in the builder, however, because if we did we couldn't tell whether the app creator wants to edit the detail screen or the list screen. This ##autoRunInTabletMode flag here is used by item renderers to decide whether they should auto-run their actions if they're the first item.