Code Annotations (Atom package)

This is an atom package for creating code annotations. An annotation is a piece of content with a title that can be displayed in Atom. Code Annotations will not show up in your code but can nonetheless be used along with a VCS.

Annotated files have a modified icon in the tree view. By default, this package provides correct styles for tree-view's default icons and the file-icons package.

Tree-view icons (file-icons)

Annotations appear as icons in the Atom gutter and can be revealed by clicking these icons.

Basic usage

By default, this package can render the 4 types of content. Further renderers can be added by

installing code-annotation plugin packages (for versions v2.x see the example plugin) or
creating Pull Requests.

An advantage over v2.x is that annotations no longer depend on code comments meaning you can effectively comment code that does not have a comment syntax (e.g. comments in package.json).

Usage

Basics

Code annotations can be added from the packages menu and of course from the command palette. New annotations are added to the current cursor's line by default (it can be changed in one of the dialogs if needed).

Multiple annotations can be attached to the same line. So explanation and images can be used together for the same chunk of code.

All annotations are saved in .annotations.cson in the project root. In v2.x there were stored in a .code-annotations directory. If such an "old" directory exists it should be detected and you should run the migrate command (see commands).

Types of annotations

`image`

Renders images as <img> tags (currently supports png, gif, jpg and bmp).

`html`

Renders HTML as you would expect - the web way of rich text.

`link`

Renders the web page belonging to a URL.

Project relative files can be displayed by using a file URL starting with file://$NAME where $NAME is a placeholder for the project named NAME.

`text`

Renders plain text.

Commands, shortcuts

Command	Shortcut	Description
`add-annotation`		Adds an annotation. Data is input using some dialogs.
`show-all`		Displays all annotations of the current project. Choosing one opens the corresponding file at the annotated line.
`edit-raw`		Opens `.annotations.cson` for editing annotations manually.
`hide-container`	`escape`	Hides/closes the annotation container.
`select-previous-annotation`	`up`	Displays the previous annotation in the list.
`select-next-annotation`	`down`	Displays the next annotation in the list.
`move-annotation-up`	`cmd-up` / `ctrl-up`	Moves the currently selected annotation up the list.
`move-annotation-down`	`cmd-down` / `ctrl-down`	Moves the currently selected annotation down the list.
`show-qr-code`		Shows the QR code that's required for the mobile app.
`migrate`		Migrates annotation data from `v2` to `v3`.

(cmd is used for macOS, ctrl for Linux and Windows.)

Showing annotations (rendering)

The container is made visible by clicking on the icon displayed in the gutter - a pin icon by default. The hide-container command closes it (which is triggered on escape).

File icons in the tree view panel

By default, a dot will be displayed below annotated files' icons. This can be turned off in the package's settings (or by setting display: none; in the :after selectors shown below).

For customizing the position of the dot add something like this to your styles.less (which you can open in via the menu: Atom > Stylesheet...).

.tree-view li.file.entry {
    // Default icons 
    &.annotated {
        span.name.icon:after {
            bottom: 0px;
            left: 12px / 2;
        }
    }
    // file-icons 
    &.annotated--file-icons {
        span.name.icon:after {
            bottom: 1px;
            left: 16px / 2;
        }
    }
}

If you use a different icon provider (other than tree-view's default icons or file-icons), customize the annotated class.

For complete customization of the icon highlighting you can add any other CSS rules, of course.

Mobile App

There is a mobile app belonging to this Atom package. It is located in the AtomCodeAnnotations folder.

The app can be used for taking photos. These photos can then be sent to Atom as code annotations. In order for the app to send the photo it needs to know an IP address which it gets by reading the QR code that can be shown with the show-qr-code command.

Distribution

iOS

The app should be deployable using Apple's Ad Hoc Distribution.

Android

TODO. These links look helpful though:

Changelog (since `v2.x`)

See releases.

Contribution

Setting up the package

apm develop code-annotations
cd ~/github/code-annotations
atom . --dev

git clone https://github.com/jneuendorf/code-annotations.git
cd code-annotations
apm link
atom .
# or 
# apm link --dev 
# atom . --dev

Thanks to

edahlseng for the motivation that led to v3.0 and ideas for improving quality and performance of the package.
bradleyDean for feedback and inspiration

code-annotations