NAME

    Yaadgom - Yet Another Automatic Document Generator (On Markdown)

SYNOPSIS

        use Yaadgom;
    
        # create an instance
        my $foo = Yaadgom->new;
    
        # call this method each request you want to document
        $foo->process_response(
            folder => 'test', # what 'folder' or 'category' this is
            weight => 1     , # default order
            req    => HTTP::Request->new ( GET => 'http://www.example.com/foobar' ),
            res    => HTTP::Response->new( 200, 'OK', [ 'content-type' => 'application/json' ], '{"ok":1}' ),
        );
    
        # iterate over processed document, for each file.
        # NOTE: This does not write to any file.
        $foo->map_results(
            sub {
                my (%info) = @_;
    
                is( $info{file},   'foobar', '"foobar" file' );
                is( $info{folder}, 'test',   '"test" folder' );
                ok( $info{str}, 'has str' );
            }
        );

DESCRIPTION

    Yaadgom helps you document your requests (to create an API Reference or
    something like that).

    Yaadgom output string in markdown format, so you can use those
    generated files on http://daux.io or github

    For each time you call "process_response" it will generate a new
    section composed of:

        ## Title with $desc
        defined $file_name ? <small>$file_name</small>
        exists $opt{extra}{name} ? > $opt{extra}{name}
        ### Request
        <pre> &format_body( $req->as_string ) </pre>
        ### Response
        <pre> &format_body( $res->as_string ) </pre>

METHODS

 new

        Yaadgom->new(
            # add file_name on the generated document fragment, if you can pass undef to disable this feature
            file_name => "$0",
    
            # in case you want to do something when this objects destroy, like call ->export_to_dir
            on_destroy => sub { .. },
        );

 process_response

        $self->process_response(
            folder => 'General',
            weight => -150, # set as "first" thing on document
            req    => HTTP::Request->new ( GET => 'http://www.example.com/login' ),
            res    => HTTP::Response->new( 200, 'OK', [ 'content-type' => 'application/json' ], '{"has_password":1}' ),
            extra => {
                 fields => { has_password => ['the user has password', 'but can came from facebook']},
                 you_can_extend_using => { 'Class_Trigger' => 'to process something else' }
            }
        );

 map_results

        iterate over processed document, for each file.
    
        $self->map_results(
            sub {
                my (%info) = @_;
    
            }
        );

 export_to_dir

        # note that this do an append operation on files, so you may reset / truncate your directory before calling this.
        # this is done because you may want multiple tests writing to same file, in different moments.
        $self->export_to_dir(
            dir => '/tmp/
        );

Class::Trigger names

    On each trigger, return is used as the new version of the input. Except
    for *process_extras*, where all return are concatenated.

    Trigger / variables:

        $self0_01->call_trigger( 'filename_generated', { req => $req, file => $file } );
        $self0_01->call_trigger( 'format_title', { header => $desc } );
        $self0_01->call_trigger( 'format_body', { response_str => $body } );
        $self0_01->call_trigger( 'format_before_extras', { str => $str } );
        $self0_01->call_trigger( 'format_after_extras', { str => $str } );
        $self0_01->call_trigger( 'process_extras', %opt );
        $self0_01->call_trigger( 'format_generated_str', { str => $format_time } );

    Updated @ Stash-REST 0.03

        $ grep  '$self_0_01->call_trigger' lib/Yaadgom.pm  | perl -ne '$_ =~ s/^\s+//; $_ =~ s/self-/self0_01-/; print' | sort | uniq

Using Stash::REST for testing and writing docs at same time

    Please read first Stash::REST SYNOPSIS to understand how to use it.

    Then, create some package that extends Stash::REST (you can call
    add_trigger on the object of Stash::REST if you want too)

        package YourProject;
    
        use base qw(Stash::REST);
        use strict;
    
        YourProject->add_trigger( 'process_response' => \&on_process_response );
    
        use Yaadgom;
    
        my $dir = $ENV{DAUX_OUTPUT_DIR};
    
        # workarround for re-using same folder when Stash::REST call get and list of an created object.
        my $reuse_last_daux_top;
        my $reuse_count;
    
        my $instance = Yaadgom->new( on_destroy => \&_on_destroy );
    
        sub on_process_response {
            my ( $self, $opt ) = @_;
    
            my %conf = %{ $opt->{conf} };
            my $req  = $opt->{req};
            my $res  = $opt->{res};
            return if ( $opt->{res}->code != $conf{code} );
            $conf{folder} = $reuse_last_daux_top if $reuse_count;
            return unless $conf{folder};
            $reuse_count--;
    
            if ( $reuse_count <= 0 ) {
                $reuse_last_daux_top = $conf{folder};
                $reuse_count = exists $conf{list} ? 2 : $conf{code} == 201 ? 1 : 0;
            }
    
            $instance->process_response(
                req    => $req,
                res    => $res,
                folder => $conf{folder},
    
                extra => { %conf }
            );
    
        }
    
        sub _on_destroy {
    
            my $going_die = shift;
            $going_die->export_to_dir( dir => $dir );
    
        }
    
        1;

    Now, after you run your script

        $obj = YourProject->new( ...)
    
        $obj->rest_post(
            '/zuzus',
            name  => 'add zuzu',
            list  => 1,
            folder => 'SomeFolder',
            params => [ name => 'foo', ]
        );

    You should have on $ENV{DAUX_OUTPUT_DIR} a SomeFolder directory with
    zuzus.md inside.

    If you copy those .md files into daux.io/docs folder, you can build
    something like this:

AUTHOR

    Renato CRON <rentocron@cpan.org>

COPYRIGHT

    Copyright 2015- Renato CRON

    Thanks to http://eokoe.com

LICENSE

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

SEE ALSO

    Shodo

SEE OTHER

    Stash::REST, Class::Trigger