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