NAME

Pod::Elemental::Transformer::Splint - Documentation from class metadata

VERSION

Version 0.1202, released 2020-12-26.

SYNOPSIS

    # in weaver.ini
    [-Transformer / Splint]
    transformer = Splint

DESCRIPTION

Pod::Elemental::Transformer::Splint uses MooseX::AttributeDocumented to add inlined documentation about attributes to pod. If you write your classes with Moops you can also document method signatures with Kavorka::TraitFor::Parameter::doc (and ::ReturnType::doc).

A class defined like this:

    package My::Class;

    use Moose;

    has has_brakes => (
        is => 'ro',
        isa => Bool,
        default => 1,
        traits => ['Documented'],
        documentation => 'Does the bike have brakes?',
        documentation_alts => {
            0 => 'Hopefully a track bike',
            1 => 'Always nice to have',
        },
    );

    =pod

    :splint classname My::Class

    :splint attributes

    =cut

Will render like this (to html):

begin

has_brakes

Bool	optional, default: 1	read-only	0:	Hopefully a track bike
			1:	Always nice to have

Does the bike have brakes?

end

A Moops class defined like this:

    class My::MoopsClass using Moose {

        ...

        method advanced_method(Int $integer                        does doc("Just an integer\nmethod_doc|This method is advanced."),
                               ArrayRef[Str|Bool] $lots_of_stuff   does doc('It works with both types'),
                               Str :$name!                         does doc("What's the name"),
                               Int :$age                           does doc('The age of the thing') = 0,
                               Str :$pseudonym                     does doc('Incognito..')
                           --> Bool but assumed                    does doc('Did it succeed?')

        ) {
            return 1;
        }

        method less_advanced($stuff,
                             $another_thing                     does doc("Don't know what we get here"),
                             ArrayRef $the_remaining is slurpy  does doc('All the remaining')
        )  {
            return 1;
        }

        ...
    }

    =pod

    :splint classname My::MoopsClass

    :splint method advanced_method

    It needs lots of documentation.

    :splint method less_advanced

    =cut

Will render like this (to html):

begin

advanced_method

This method is advanced.

Positional parameters
$integer	Int	required		Just an integer
$lots_of_stuff	ArrayRef[ Str | Bool ]	required		It works with both types
Named parameters
name => $value	Str	required		What's the name
age => $value	Int	optional, default = 0		The age of the thing
pseudonym => $value	Str	optional, no default		Incognito..
Returns
Bool				Did it succeed?

It needs lots of documentation.

less_advanced

Positional parameters
$stuff		required
$another_thing		required		Don't know what we get here
$the_remaining	ArrayRef	required	slurpy	All the remaining

end

ATTRIBUTES

The following settings are available in weaver.ini:

command_name

Default: :splint

Defines the command used at the beginning of the line in pod.

attribute_renderer

Default: HTML=HtmlDefault, markdown=HtmlDefault

Define which renderers to use. Comma separated list of pairs where the key defines the format in pod and the value defines the renderer (in the Pod::Elemental::Transformer::Splint::AttributeRenderer namespace).

The default will render each attribute like this:

    =begin HTML

    <!-- attribute information -->

    =end HTML

    =begin markdown

    <!-- attribute information -->

    =end markdown

method_renderer

Default: HTML=HtmlDefault, markdown=HtmlDefault

Similar to "attribute_renderer" but for methods. This is currently only assumed to work for methods defined with Kavorka or Moops.

Method renderers are in the Pod::Elemental::Transformer::Splint::MethodRenderer namespace.

type_libraries

Default: undef

If you use Type::Tiny based type libraries, the types are usually linked to the correct library. Under some circumstances it might be necessary to specify which library a certain type belongs to.

It is a space separated list:

    type_libraries = Custom::Types=AType Types::Standard=Str,Int

default_type_library

Default: Types::Standard

The default Type::Tiny based type library to link types to.

SOURCE

https://github.com/Csson/p5-Pod-Elemental-Transformer-Splint

HOMEPAGE

https://metacpan.org/release/Pod-Elemental-Transformer-Splint

AUTHOR

Erik Carlsson <info@code301.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Erik Carlsson.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Pod::Elemental::Transformer::Splint

perl -MCPAN -e shell
install Pod::Elemental::Transformer::Splint