/ 
Dancer-Plugin-Documentation-0.02
River stage zero No dependents
/ Dancer::Plugin::Documentation

NAME

Dancer::Plugin::Documentation - register documentation for routes

VERSION

Version 0.02

SYNOPSIS

Dancer::Plugin::Documentation provides a few keywords to associate documentation with a fully pathed route. This is especially useful when the route path is externally modified by the prefix command. Documentation my be anything from a string to a complex data structure.

Example usage:

package Foo;

use Dancer;
use Dancer::Plugin::Documentation qw{:all};

document_section 'Helpers';

document_route 'Display documentation'
get '/resources' => sub {
	status 200;
	return join "\n\n",
		map {
			$_->isa('Dancer::Plugin::Documentation::Section') ? ($_->section, $_->documentation || ()) :
			$_->isa('Dancer::Plugin::Documentation::Route') ? ($_->method . ' ' . $_->path, $_->documentation) :
				$_->documentation
		} documentation;
};

prefix '/v1';

document_section 'Foo', 'Manage your foo';

document_route 'A route to retrieve foo',
get '/foo' => sub { status 200; return 'foo' };

package main;

dance;

KEYWORDS

document_route

Given a documentation argument and a list of routes, associate the documentation with all of the routes.

document_section

Given a label, set the section grouping for all subsequent document_route calls. Optionally, supply documentation to associate with the section. Disable the current section by passing undef or the empty string for the label.

documentation

Retrieve all documentation for the current app with sections interweaved with routes. Supports all arguments for documentation_for_routes and documentation_for_sections.

documentation_for_routes

Retrieve all route documentation for the current app. Supports all the same arguments as get_route_documentation besides app.

documentation_for_sections

Retrieve all section documentation for the current app. Supports all the same arguments as get_section_documentation besides app.

DOCUMENTATION METHODS

get_route_documentation

Retrieve the route documentation for an app in lexicographical order by section, route, then method. Any/all of the following may be supplied to filter the documentation: method, path, section

get_section_documentation

Retrieve the section documentation for an app in lexicographical order. Any/all of the following may be supplied to filter the documentation: section

set_route_documentation

Register documentation for the method and route of a particular app.

set_section_documentation

Register documentation for the section of a particular app.

APPLICATION STATE METHODS

get_active_section

Get the name of the active section for the application.

set_active_section

Set the name of the active section for the application.

CAVEATS

any

The documentation keyword does not work with the any keyword as it does not return the list of registered routes, but rather the number of routes registered. Fixing this behavior will require a patch to Dancer.

get

The get keyword generates both get and head routes. Documentation will be attached to both.

AUTHOR

Aaron Cohen, <aarondcohen at gmail.com>

ACKNOWLEDGEMENTS

This module was made possible by Shutterstock (@ShutterTech). Additional open source projects from Shutterstock can be found at code.shutterstock.com.

BUGS

Please report any bugs or feature requests to bug-Dancer-Plugin-Documentation at rt.cpan.org, or through the web interface at https://github.com/aarondcohen/perl-dancer-plugin-documentation/issues. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Dancer::Plugin::Documentation

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2014 Aaron Cohen.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.