atomdocr

A helper package for writing AtomDoc style documentation

Garth Braithwaite

212

1

1.0.0

Apache-2.0

GitHub

This package consumes the following services:

AtomDocr Package

A fork of DockBlockr but aimed at AtomDoc syntax.

AtomDocr is a package for Atom which is designed to make writing documentation faster and easier.

The package currently supports the following languages -

Installing

Use the Atom package manager, which can be found in the Settings view or run apm install atomdocr from the command line.

Feature requests & bug reports

The main development branch is develop and the stable 'production' branch is master. Please remember to base your branch from develop and issue the pull request back to that branch.

Usage

Below are some examples of what the package does. Note that there are no keyboard shortcuts required to trigger these completions - just type as normal and it happens for you!

AtomDoc completion

Pressing enter or tab after /** (or ###* for Coffee-Script) will yield a new line and will close the comment.

Single-asterisk comment blocks behave similarly:

Function documentation

However, if the line directly afterwards contains a function definition, then its name and parameters are parsed and some documentation is automatically added.

You can then press tab to move between the different fields.

If you have many arguments, or long variable names, it might be useful to spread your arguments across multiple lines. AtomDocr will handle this situation too:

In languages which support type hinting or default values, then those types are prefilled as the datatypes.

AtomDocr will try to make an intelligent guess about the return value of the function.

Variable documentation

If the line following your AtomDoc contains a variable declaration, AtomDocr will try to determine the data type of the variable and insert that into the comment.

If you press shift+enter after the opening /** then the docblockr will be inserted inline.

AtomDocr will also try to determine the type of the variable from its name. Variables starting with is or has are assumed to be booleans, and callback, cb, done, fn, and next are assumed to be functions. If you use your own variable naming system (eg: hungarian notation: booleans all start with b, arrays start with arr), you can define these rules yourself.

Comment extension

Pressing enter inside a AtomDocr will automatically insert a leading asterisk and maintain your indentation.

This applies to AtomDocr comments /** like this */ as well as inline double-slash comments // like this

In either case, you can press shift+enter to stop the automatic extension.

Oftentimes, when documenting a parameter, or adding a description to a tag, your description will cover multiple lines. If the line you are on is directly following a tag line, pressing tab will move the indentation to the correct position.

Multiline comment decoration

If you write a multiline comment and use AtomDocr:Decorate Multiline, AtomDocr will create block comment decoration.

Comment decoration

If you write a double-slash comment and then use AtomDocr:Decorate, AtomDocr will 'decorate' that line for you.

// Foo bar baz<<AtomDocr:Decorate>>

-- becomes

/////////////////
// Foo bar baz //
/////////////////

Reparsing a AtomDoc

Sometimes, you'll perform some action which clears the fields (sections of text which you can navigate through using tab). This leaves you with a number of placeholders in the AtomDoc with no easy way to jump to them.

With AtomDocr, you can reparse a comment and reactivate the fields by using command AtomDocr:Reparse

Reformatting paragraphs

Inside a comment block, hit AtomDocr:Wrap Lines to wrap the lines to make them fit within your rulers. If you would like subsequent lines in a paragraph to be indented, you can adjust the indentation_spaces_same_para setting. For example, a value of 3 might look like this:

/**
 * Duis sed arcu non tellus eleifend ullamcorper quis non erat. Curabitur
 *   metus elit, ultrices et tristique a, blandit at justo.
 * @param  {String} foo Lorem ipsum dolor sit amet.
 * @param  {Number} bar Nullam fringilla feugiat pretium. Quisque
 *   consectetur, risus eu pellentesque tincidunt, nulla ipsum imperdiet
 *   massa, sit amet adipiscing dolor.
 * @return {[Type]}
 */

Configuration

You can access the configuration settings by entering AtomDocr in atom settings window

// indentation_spaces = 1
/**
 * foo
 */

// indentation_spaces = 5
/**
 *     foo
 */

Note

All credits for this package goes to SublimeJsdocs who have created a wonderful plugin for Sublime Text. I have just ported the package to Atom and Javascript.

All features except macros have been implemented. Please create issues for bugs.

TODO

Add test cases.