diff --git a/modules/swagger-codegen/src/main/resources/perl/AutoDoc.mustache b/modules/swagger-codegen/src/main/resources/perl/AutoDoc.mustache
index ba0edd840ff..76da048b069 100644
--- a/modules/swagger-codegen/src/main/resources/perl/AutoDoc.mustache
+++ b/modules/swagger-codegen/src/main/resources/perl/AutoDoc.mustache
@@ -28,11 +28,16 @@ sub _printisa {
 	my $sub =   join ', ', $meta->subclasses;
 	my $dsub =  join ', ', $meta->direct_subclasses;
 	
+    my $app_name = $self->version_info->{app_name};
+    my $app_version = $self->version_info->{app_version};
+    my $generated_date = $self->version_info->{generated_date};
+    my $generator_class = $self->version_info->{generator_class};
+
+    $~ = $how eq 'pod' ? 'INHERIT_POD' : 'INHERIT';
+    write;
+	
 	my ($rolepkg, $role_reqs);
 	
-	$~ = $how eq 'pod' ? 'INHERIT_POD' : 'INHERIT';
-	write;
-
 	foreach my $role (@roles) {
 		$rolepkg = $role->{package} || next; # some are anonymous, or something
 		next if $rolepkg eq 'WWW::{{moduleName}}::Role::AutoDoc';
@@ -58,6 +63,14 @@ $myclass
                        $dsub
        All subclasses: @*
                        $sub
+                       
+           Target API: @* @*
+                       $app_name, $app_version
+         Generated on: @*
+                       $generated_date
+      Generator class: @* 
+                       $generator_class
+                       
 .
 	format ROLES =   
              Composes: ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
@@ -74,6 +87,26 @@ $myclass
 @*
 $myclass
 
+=head1 VERSION
+
+=head2 @* version: @*
+       $app_name,  $app_version
+       
+Automatically generated by the Perl Swagger Codegen project: 
+
+=over 4 
+
+=item Build date: @*
+                  $generated_date
+
+=item Build package: @*
+                     $generator_class
+
+=item Codegen version: 
+
+
+=back
+
 =head1 INHERITANCE
 
 =head2 Base class(es) 
@@ -90,6 +123,7 @@ $dsub
 
 @*
 $sub
+
                 
 =head1 COMPOSITION
 
@@ -171,6 +205,9 @@ sub _printmethod {
 		$original_pkg = $on; 
 		$doc = $original_pkg->method_documentation->{$delegate_to}->{summary};
 	}
+	else {
+	    $doc = $method->documentation;
+	}
 	
 	if ($how eq 'narrow') {
 		$~ = 'METHOD_NARROW';
@@ -302,7 +339,7 @@ sub _printattr {
 	my $from = $attr->associated_class->name || '';
 	my $reqd = $attr->is_required ? 'yes' : 'no';
 	my $lazy = $attr->is_lazy ? 'yes' : 'no';
-	my $has_doc = $attr->has_documentation ? 'yes' : 'no';
+	my $has_doc = $attr->has_documentation ? 'yes' : 'no'; # *_api attributes will never have doc, but other attributes might have
 	my $doc = $attr->documentation || '';
 	my $handles = join ', ', sort @{$attr->handles || []};
 	$handles ||= '';
diff --git a/modules/swagger-codegen/src/main/resources/perl/README.md b/modules/swagger-codegen/src/main/resources/perl/README.md
index 7d0f62dca4b..2e7e57a2c57 100644
--- a/modules/swagger-codegen/src/main/resources/perl/README.md
+++ b/modules/swagger-codegen/src/main/resources/perl/README.md
@@ -1,6 +1,16 @@
 # NAME
 
-WWW::{{moduleName}}::Role - a Moose role for the Perl Swagger Codegen project
+WWW::{{moduleName}}::Role - a Moose role for the {{appName}} 
+
+## {{appName}} version: {{appVersion}}
+
+# VERSION
+
+Automatically generated by the Perl Swagger Codegen project: 
+
+- Build date: {{generatedDate}}
+- Build package: {{generatorClass}}
+- Codegen version: 
 
 ## A note on Moose
 
@@ -185,6 +195,7 @@ output formats are supported:
     -n           narrow format
     -p           POD format 
     -H           HTML format 
+    -m           Markdown format
     -h           print this help message
     -c           your application class
     
diff --git a/modules/swagger-codegen/src/main/resources/perl/Role.mustache b/modules/swagger-codegen/src/main/resources/perl/Role.mustache
index 0ad2573016e..06c230955d8 100644
--- a/modules/swagger-codegen/src/main/resources/perl/Role.mustache
+++ b/modules/swagger-codegen/src/main/resources/perl/Role.mustache
@@ -10,25 +10,39 @@ use WWW::{{moduleName}}::ApiFactory;
 has base_url => ( is => 'ro',
 				  required => 0,
 				  isa => 'Str',
+				  documentation => 'Root of the server that requests are sent to',
 				  );
 
 has api_factory => ( is => 'ro',
 					 isa => 'WWW::{{moduleName}}::ApiFactory',
 					 builder => '_build_af', 
 					 lazy => 1,
+					 documentation => 'Builds an instance of the endpoint API class',
 					 );
 
 has tokens => ( is => 'ro',
 				isa => 'HashRef',
 				required => 0,
-				default => sub {{=<% %>=}}{{}}<%={{ }}=%>, # ! 
+				default => sub { {} },
+				documentation => 'The auth tokens required by the application - basic, OAuth and/or API key(s)',
 				);
 
 has _cfg => ( is => 'ro',
 			  isa => 'Str',
 			  default => 'WWW::{{moduleName}}::Configuration',
 			  );
-					 
+
+has version_info => ( is => 'ro', 
+	                  isa => 'HashRef', 
+	                  default => sub { {
+	                  	  app_name => '{{appName}}',
+	                  	  app_version => '{{appVersion}}',
+	                  	  generated_date => '{{generatedDate}}',
+	                  	  generator_class => '{{generatorClass}}',
+	                  } },
+	                  documentation => 'Information about the application version and the codegen codebase version'
+	                  );
+
 sub BUILD {
 	my $self = shift;
 	
@@ -66,7 +80,6 @@ sub BUILD {
 									default => sub {$self->api_factory->get_api($api_name)},
 									lazy => 1,
 									handles => \@delegated,
-									documentation => $api_class->class_documentation->{description}, # not populated yet
 									) );
 	}
 }
@@ -80,7 +93,23 @@ sub _build_af {
 
 =head1 NAME
 
-WWW::{{moduleName}}::Role - a Moose role for the Perl Swagger Codegen project
+WWW::{{moduleName}}::Role - a Moose role for the {{appName}} 
+
+=head2 {{appName}} version: {{appVersion}}
+
+=head1 VERSION
+
+Automatically generated by the Perl Swagger Codegen project: 
+
+=over 4 
+
+=item Build date: {{generatedDate}}
+
+=item Build package: {{generatorClass}}
+
+=item Codegen version: 
+
+=back
 
 =head2 A note on Moose
 
@@ -268,12 +297,13 @@ output formats are supported:
   -n           narrow format
   -p           POD format 
   -H           HTML format 
+  -m           Markdown format
   -h           print this help message
   -c           your application class
   
 The C<-c> option allows you to load and inspect your own application. A dummy
 namespace is used if you don't supply your own class.
-	
+
 =head1 DOCUMENTATION FROM THE SWAGGER SPEC
 
 Additional documentation for each class and method may be provided by the Swagger 
diff --git a/modules/swagger-codegen/src/main/resources/perl/api.mustache b/modules/swagger-codegen/src/main/resources/perl/api.mustache
index f9312b994b3..d6dd9d598e1 100644
--- a/modules/swagger-codegen/src/main/resources/perl/api.mustache
+++ b/modules/swagger-codegen/src/main/resources/perl/api.mustache
@@ -33,11 +33,6 @@ use WWW::{{moduleName}}::Configuration;
 use base "Class::Data::Inheritable";
 
 __PACKAGE__->mk_classdata('method_documentation' => {});
-__PACKAGE__->mk_classdata('class_documentation' => {}); 
-
-__PACKAGE__->class_documentation({description => '',    # TODO
-                                  class => '{{classname}}',
-}                                 );
 
 sub new {
     my $class   = shift;
diff --git a/modules/swagger-codegen/src/main/resources/perl/autodoc.script.mustache b/modules/swagger-codegen/src/main/resources/perl/autodoc.script.mustache
index d669119c28b..240936d9b51 100644
--- a/modules/swagger-codegen/src/main/resources/perl/autodoc.script.mustache
+++ b/modules/swagger-codegen/src/main/resources/perl/autodoc.script.mustache
@@ -7,7 +7,7 @@ use Moose::Util qw(apply_all_roles);
 use Getopt::Std;
  
 my %options=();
-getopts("wnphHc:", \%options);
+getopts("wnphmHc:", \%options);
 help if $options{h};
 
 my $my_app = $options{c} || 'My::App';
@@ -28,10 +28,13 @@ else {
 package main;
 
 my $opt;
-$opt = 'pod' if $options{p};
 $opt = 'wide' if $options{w};
 $opt = 'narrow' if $options{n};
+
+$opt = 'pod' if $options{p};
 $opt = 'pod' if $options{H};
+$opt = 'pod' if $options{m};
+
 $opt ||= 'wide';
 
 my $api = $my_app->new;
@@ -42,6 +45,12 @@ if ($options{H}) {
 	$api->autodoc($opt);
 	close STDOUT or die "Can't close: $!";
 }
+elsif ($options{m}) {
+	my $pod2markdown = "pod2markdown --html-encode-chars 1";
+	open STDOUT, "| $pod2markdown" or die "Can't fork: $!";
+	$api->autodoc($opt);
+	close STDOUT or die "Can't close: $!";
+}
 else {
 	$api->autodoc($opt);
 }
@@ -57,6 +66,7 @@ Usage: autodoc [OPTION] [-c My::App::Class]
   -n           narrow format
   -p           POD format 
   -H           HTML format 
+  -m           Markdown format
   -h           print this help message
   -c           your application class
 
diff --git a/samples/client/petstore/perl/README.md b/samples/client/petstore/perl/README.md
index fd237d92d4c..289ce461777 100644
--- a/samples/client/petstore/perl/README.md
+++ b/samples/client/petstore/perl/README.md
@@ -1,208 +1,281 @@
 # NAME
 
-WWW::SwaggerClient::Role - a Moose role for the Perl Swagger Codegen project
+My::App
 
-## A note on Moose
+# VERSION
 
-This role is the only component of the library that uses Moose. See 
-WWW::SwaggerClient::ApiFactory for non-Moosey usage. 
+## Swagger Petstore version: 1.0.0
 
-# SYNOPSIS
+Automatically generated by the Perl Swagger Codegen project:
 
-The Perl Swagger Codegen project builds a library of Perl modules to interact with 
-a web service defined by a Swagger specification. See below for how to build the 
-library.
+- Build date: 2015-11-13T18:23:57.025Z
+- Build package: class io.swagger.codegen.languages.PerlClientCodegen
+- Codegen version:
 
-This module provides an interface to the generated library. All the classes, 
-objects, and methods (well, not quite \*all\*, see below) are flattened into this 
-role. 
+# INHERITANCE
 
-        package MyApp;
-        use Moose;
-        with 'WWW::SwaggerClient::Role';
-        
-        package main;
-        
-        my $api = MyApp->new({ tokens => $tokens });
-        
-        my $pet = $api->get_pet_by_id(pet_id => $pet_id);
-        
+## Base class(es)
 
-## Structure of the library
+Moose::Object
 
-The library consists of a set of API classes, one for each endpoint. These APIs
-implement the method calls available on each endpoint. 
+## Direct subclasses
 
-Additionally, there is a set of "object" classes, which represent the objects 
-returned by and sent to the methods on the endpoints. 
+## All subclasses
 
-An API factory class is provided, which builds instances of each endpoint API. 
+# COMPOSITION
 
-This Moose role flattens all the methods from the endpoint APIs onto the consuming 
-class. It also provides methods to retrieve the endpoint API objects, and the API 
-factory object, should you need it. 
+My::App composes the following roles:
 
-For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.
+## `WWW::SwaggerClient::Role`
 
-## Configuring authentication
-
-In the normal case, the Swagger spec will describe what parameters are
-required and where to put them. You just need to supply the tokens.
-
-    my $tokens = {
-        # basic
-        username => $username,
-        password => $password,
-        
-        # oauth
-        access_token => $oauth_token,
-        
-        # keys
-        $some_key => { token => $token,
-                       prefix => $prefix, 
-                       in => $in,             # 'head||query',     
-                       },
-                       
-        $another => { token => $token,
-                      prefix => $prefix, 
-                      in => $in,              # 'head||query',      
-                      },                   
-        ...,
-        
-        };
-        
-        my $api = MyApp->new({ tokens => $tokens });
-
-Note these are all optional, as are `prefix` and `in`, and depend on the API
-you are accessing. Usually `prefix` and `in` will be determined by the code generator from
-the spec and you will not need to set them at run time. If not, `in` will
-default to 'head' and `prefix` to the empty string. 
-
-The tokens will be placed in the `WWW::SwaggerClient::Configuration` namespace
-as follows, but you don't need to know about this. 
-
-- `$WWW::SwaggerClient::Configuration::username`
-
-    String. The username for basic auth.
-
-- `$WWW::SwaggerClient::Configuration::password`
-
-    String. The password for basic auth.
-
-- `$WWW::SwaggerClient::Configuration::api_key`
-
-    Hashref. Keyed on the name of each key (there can be multiple tokens).
-
-            $WWW::SwaggerClient::Configuration::api_key = {
-                    secretKey => 'aaaabbbbccccdddd',
-                    anotherKey => '1111222233334444',
-                    };
-
-- `$WWW::SwaggerClient::Configuration::api_key_prefix`
-
-    Hashref. Keyed on the name of each key (there can be multiple tokens). Note not
-    all api keys require a prefix.
-
-            $WWW::SwaggerClient::Configuration::api_key_prefix = {
-                    secretKey => 'string',
-                    anotherKey => 'same or some other string',
-                    };
-
-- `$WWW::SwaggerClient::Configuration::access_token`
-
-    String. The OAuth access token. 
+Requires:
 
 # METHODS
 
-## `base_url`
+## `add_pet()`
 
-The generated code has the `base_url` already set as a default value. This method 
-returns (and optionally sets, but only if the API client has not been 
-created yet) the current value of `base_url`.
+       Defined in: WWW::SwaggerClient::PetApi
+     Delegates to: add_pet()
+               On: WWW::SwaggerClient::PetApi
+              Via: pet_api()
+              Doc: Add a new pet to the store
+          Same as: $self->pet_api->add_pet()
+
+## `create_user()`
+
+       Defined in: WWW::SwaggerClient::UserApi
+     Delegates to: create_user()
+               On: WWW::SwaggerClient::UserApi
+              Via: user_api()
+              Doc: Create user
+          Same as: $self->user_api->create_user()
+
+## `create_users_with_array_input()`
+
+       Defined in: WWW::SwaggerClient::UserApi
+     Delegates to: create_users_with_array_input()
+               On: WWW::SwaggerClient::UserApi
+              Via: user_api()
+              Doc: Creates list of users with given input array
+          Same as: $self->user_api->create_users_with_array_input()
+
+## `create_users_with_list_input()`
+
+       Defined in: WWW::SwaggerClient::UserApi
+     Delegates to: create_users_with_list_input()
+               On: WWW::SwaggerClient::UserApi
+              Via: user_api()
+              Doc: Creates list of users with given input array
+          Same as: $self->user_api->create_users_with_list_input()
+
+## `delete_order()`
+
+       Defined in: WWW::SwaggerClient::StoreApi
+     Delegates to: delete_order()
+               On: WWW::SwaggerClient::StoreApi
+              Via: store_api()
+              Doc: Delete purchase order by ID
+          Same as: $self->store_api->delete_order()
+
+## `delete_pet()`
+
+       Defined in: WWW::SwaggerClient::PetApi
+     Delegates to: delete_pet()
+               On: WWW::SwaggerClient::PetApi
+              Via: pet_api()
+              Doc: Deletes a pet
+          Same as: $self->pet_api->delete_pet()
+
+## `delete_user()`
+
+       Defined in: WWW::SwaggerClient::UserApi
+     Delegates to: delete_user()
+               On: WWW::SwaggerClient::UserApi
+              Via: user_api()
+              Doc: Delete user
+          Same as: $self->user_api->delete_user()
+
+## `find_pets_by_status()`
+
+       Defined in: WWW::SwaggerClient::PetApi
+     Delegates to: find_pets_by_status()
+               On: WWW::SwaggerClient::PetApi
+              Via: pet_api()
+              Doc: Finds Pets by status
+          Same as: $self->pet_api->find_pets_by_status()
+
+## `find_pets_by_tags()`
+
+       Defined in: WWW::SwaggerClient::PetApi
+     Delegates to: find_pets_by_tags()
+               On: WWW::SwaggerClient::PetApi
+              Via: pet_api()
+              Doc: Finds Pets by tags
+          Same as: $self->pet_api->find_pets_by_tags()
+
+## `get_inventory()`
+
+       Defined in: WWW::SwaggerClient::StoreApi
+     Delegates to: get_inventory()
+               On: WWW::SwaggerClient::StoreApi
+              Via: store_api()
+              Doc: Returns pet inventories by status
+          Same as: $self->store_api->get_inventory()
+
+## `get_order_by_id()`
+
+       Defined in: WWW::SwaggerClient::StoreApi
+     Delegates to: get_order_by_id()
+               On: WWW::SwaggerClient::StoreApi
+              Via: store_api()
+              Doc: Find purchase order by ID
+          Same as: $self->store_api->get_order_by_id()
+
+## `get_pet_by_id()`
+
+       Defined in: WWW::SwaggerClient::PetApi
+     Delegates to: get_pet_by_id()
+               On: WWW::SwaggerClient::PetApi
+              Via: pet_api()
+              Doc: Find pet by ID
+          Same as: $self->pet_api->get_pet_by_id()
+
+## `get_user_by_name()`
+
+       Defined in: WWW::SwaggerClient::UserApi
+     Delegates to: get_user_by_name()
+               On: WWW::SwaggerClient::UserApi
+              Via: user_api()
+              Doc: Get user by user name
+          Same as: $self->user_api->get_user_by_name()
+
+## `login_user()`
+
+       Defined in: WWW::SwaggerClient::UserApi
+     Delegates to: login_user()
+               On: WWW::SwaggerClient::UserApi
+              Via: user_api()
+              Doc: Logs user into the system
+          Same as: $self->user_api->login_user()
+
+## `logout_user()`
+
+       Defined in: WWW::SwaggerClient::UserApi
+     Delegates to: logout_user()
+               On: WWW::SwaggerClient::UserApi
+              Via: user_api()
+              Doc: Logs out current logged in user session
+          Same as: $self->user_api->logout_user()
+
+## `place_order()`
+
+       Defined in: WWW::SwaggerClient::StoreApi
+     Delegates to: place_order()
+               On: WWW::SwaggerClient::StoreApi
+              Via: store_api()
+              Doc: Place an order for a pet
+          Same as: $self->store_api->place_order()
+
+## `update_pet()`
+
+       Defined in: WWW::SwaggerClient::PetApi
+     Delegates to: update_pet()
+               On: WWW::SwaggerClient::PetApi
+              Via: pet_api()
+              Doc: Update an existing pet
+          Same as: $self->pet_api->update_pet()
+
+## `update_pet_with_form()`
+
+       Defined in: WWW::SwaggerClient::PetApi
+     Delegates to: update_pet_with_form()
+               On: WWW::SwaggerClient::PetApi
+              Via: pet_api()
+              Doc: Updates a pet in the store with form data
+          Same as: $self->pet_api->update_pet_with_form()
+
+## `update_user()`
+
+       Defined in: WWW::SwaggerClient::UserApi
+     Delegates to: update_user()
+               On: WWW::SwaggerClient::UserApi
+              Via: user_api()
+              Doc: Updated user
+          Same as: $self->user_api->update_user()
+
+## `upload_file()`
+
+       Defined in: WWW::SwaggerClient::PetApi
+     Delegates to: upload_file()
+               On: WWW::SwaggerClient::PetApi
+              Via: pet_api()
+              Doc: uploads an image
+          Same as: $self->pet_api->upload_file()
+
+# ATTRIBUTES
 
 ## `api_factory`
 
-Returns an API factory object. You probably won't need to call this directly. 
+         is: ro
+        isa: WWW::SwaggerClient::ApiFactory
+       reqd: no
+       lazy: yes
+        doc: Builds an instance of the endpoint API class
+    handles:
 
-        $self->api_factory('Pet'); # returns a WWW::SwaggerClient::PetApi instance
-        
-        $self->pet_api;                    # the same
+## `base_url`
 
-# MISSING METHODS
+         is: ro
+        isa: Str
+       reqd: no
+       lazy: no
+        doc: Root of the server that requests are sent to
+    handles:
 
-Most of the methods on the API are delegated to individual endpoint API objects
-(e.g. Pet API, Store API, User API etc). Where different endpoint APIs use the
-same method name (e.g. `new()`), these methods can't be delegated. So you need
-to call `$api->pet_api->new()`.
+## `pet_api`
 
-In principle, every API is susceptible to the presence of a few, random, undelegatable 
-method names. In practice, because of the way method names are constructed, it's 
-unlikely in general that any methods will be undelegatable, except for: 
+         is: ro
+        isa: WWW::SwaggerClient::PetApi
+       reqd: no
+       lazy: yes
+        doc:
+    handles: add_pet, delete_pet, find_pets_by_status, find_pets_by_tags,
+             get_pet_by_id, update_pet, update_pet_with_form, upload_file
 
-        new()
-        class_documentation()
-        method_documentation()
+## `store_api`
 
-To call these methods, you need to get a handle on the relevant object, either
-by calling `$api->foo_api` or by retrieving an object, e.g.
-`$api->get_pet_by_id(pet_id => $pet_id)`. They are class methods, so
-you could also call them on class names.
+         is: ro
+        isa: WWW::SwaggerClient::StoreApi
+       reqd: no
+       lazy: yes
+        doc:
+    handles: delete_order, get_inventory, get_order_by_id, place_order
 
-# BUILDING YOUR LIBRARY
+## `tokens`
 
-See the homepage `https://github.com/swagger-api/swagger-codegen` for full details. 
-But briefly, clone the git repository, build the codegen codebase, set up your build 
-config file, then run the API build script. You will need git, Java 7 and Apache 
-maven 3.0.3 or better already installed.
+         is: ro
+        isa: HashRef
+       reqd: no
+       lazy: no
+        doc: The auth tokens required by the application - basic, OAuth and/or API key(s)
+    handles:
 
-The config file should specify the project name for the generated library: 
+## `user_api`
 
-        {"moduleName":"MyProjectName"}
+         is: ro
+        isa: WWW::SwaggerClient::UserApi
+       reqd: no
+       lazy: yes
+        doc:
+    handles: create_user, create_users_with_array_input,
+             create_users_with_list_input, delete_user, get_user_by_name,
+             login_user, logout_user, update_user
 
-Your library files will be built under `WWW::MyProjectName`.
+## `version_info`
 
-          $ git clone https://github.com/swagger-api/swagger-codegen.git
-          $ cd swagger-codegen
-          $ mvn package
-          $ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-    -i [URL or file path to JSON swagger API spec] \
-    -l perl \
-    -c /path/to/config/file.json \
-    -o /path/to/output/folder
-
-Bang, all done. Run the `autodoc` script in the `bin` directory to see the API 
-you just built. 
-
-# AUTOMATIC DOCUMENTATION
-
-You can print out a summary of the generated API by running the included
-`autodoc` script in the `bin` directory of your generated library. A few
-output formats are supported:
-
-          Usage: autodoc [OPTION]
-
-    -w           wide format (default)
-    -n           narrow format
-    -p           POD format 
-    -H           HTML format 
-    -h           print this help message
-    -c           your application class
-    
-
-The `-c` option allows you to load and inspect your own application. A dummy
-namespace is used if you don't supply your own class.
-
-# DOCUMENTATION FROM THE SWAGGER SPEC
-
-Additional documentation for each class and method may be provided by the Swagger 
-spec. If so, this is available via the `class_documentation()` and 
-`method_documentation()` methods on each generated API and class: 
-
-        my $cdoc = $api->pet_api->class_documentation;                                   
-        my $cmdoc = $api->pet_api->method_documentation->{$method_name}; 
-        
-        my $odoc = $api->get_pet_by_id->(pet_id => $pet_id)->class_documentation;                                  
-        my $omdoc = $api->get_pet_by_id->(pet_id => $pet_id)->method_documentation->{method_name}; 
-        
-
-Each of these calls returns a hashref with various useful pieces of information.	
+         is: ro
+        isa: HashRef
+       reqd: no
+       lazy: no
+        doc: Information about the application version and the codegen codebase version
+    handles:
diff --git a/samples/client/petstore/perl/bin/autodoc b/samples/client/petstore/perl/bin/autodoc
index 9c167d7a41b..049fcf7fecf 100644
--- a/samples/client/petstore/perl/bin/autodoc
+++ b/samples/client/petstore/perl/bin/autodoc
@@ -7,7 +7,7 @@ use Moose::Util qw(apply_all_roles);
 use Getopt::Std;
  
 my %options=();
-getopts("wnphHc:", \%options);
+getopts("wnphmHc:", \%options);
 help if $options{h};
 
 my $my_app = $options{c} || 'My::App';
@@ -28,10 +28,13 @@ else {
 package main;
 
 my $opt;
-$opt = 'pod' if $options{p};
 $opt = 'wide' if $options{w};
 $opt = 'narrow' if $options{n};
+
+$opt = 'pod' if $options{p};
 $opt = 'pod' if $options{H};
+$opt = 'pod' if $options{m};
+
 $opt ||= 'wide';
 
 my $api = $my_app->new;
@@ -42,6 +45,12 @@ if ($options{H}) {
 	$api->autodoc($opt);
 	close STDOUT or die "Can't close: $!";
 }
+elsif ($options{m}) {
+	my $pod2markdown = "pod2markdown --html-encode-chars 1";
+	open STDOUT, "| $pod2markdown" or die "Can't fork: $!";
+	$api->autodoc($opt);
+	close STDOUT or die "Can't close: $!";
+}
 else {
 	$api->autodoc($opt);
 }
@@ -57,6 +66,7 @@ Usage: autodoc [OPTION] [-c My::App::Class]
   -n           narrow format
   -p           POD format 
   -H           HTML format 
+  -m           Markdown format
   -h           print this help message
   -c           your application class
 
diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm
index 7c632f44504..6c415d8e846 100644
--- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm
+++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm
@@ -33,11 +33,6 @@ use WWW::SwaggerClient::Configuration;
 use base "Class::Data::Inheritable";
 
 __PACKAGE__->mk_classdata('method_documentation' => {});
-__PACKAGE__->mk_classdata('class_documentation' => {}); 
-
-__PACKAGE__->class_documentation({description => '',    # TODO
-                                  class => 'PetApi',
-}                                 );
 
 sub new {
     my $class   = shift;
diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm
index e2797bf8b8f..9e719c7d574 100644
--- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm
+++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm
@@ -10,25 +10,39 @@ use WWW::SwaggerClient::ApiFactory;
 has base_url => ( is => 'ro',
 				  required => 0,
 				  isa => 'Str',
+				  documentation => 'Root of the server that requests are sent to',
 				  );
 
 has api_factory => ( is => 'ro',
 					 isa => 'WWW::SwaggerClient::ApiFactory',
 					 builder => '_build_af', 
 					 lazy => 1,
+					 documentation => 'Builds an instance of the endpoint API class',
 					 );
 
 has tokens => ( is => 'ro',
 				isa => 'HashRef',
 				required => 0,
-				default => sub {{}}, # ! 
+				default => sub { {} },
+				documentation => 'The auth tokens required by the application - basic, OAuth and/or API key(s)',
 				);
 
 has _cfg => ( is => 'ro',
 			  isa => 'Str',
 			  default => 'WWW::SwaggerClient::Configuration',
 			  );
-					 
+
+has version_info => ( is => 'ro', 
+	                  isa => 'HashRef', 
+	                  default => sub { {
+	                  	  app_name => 'Swagger Petstore',
+	                  	  app_version => '1.0.0',
+	                  	  generated_date => '2015-11-13T18:23:57.025Z',
+	                  	  generator_class => 'class io.swagger.codegen.languages.PerlClientCodegen',
+	                  } },
+	                  documentation => 'Information about the application version and the codegen codebase version'
+	                  );
+
 sub BUILD {
 	my $self = shift;
 	
@@ -66,7 +80,6 @@ sub BUILD {
 									default => sub {$self->api_factory->get_api($api_name)},
 									lazy => 1,
 									handles => \@delegated,
-									documentation => $api_class->class_documentation->{description}, # not populated yet
 									) );
 	}
 }
@@ -80,7 +93,23 @@ sub _build_af {
 
 =head1 NAME
 
-WWW::SwaggerClient::Role - a Moose role for the Perl Swagger Codegen project
+WWW::SwaggerClient::Role - a Moose role for the Swagger Petstore 
+
+=head2 Swagger Petstore version: 1.0.0
+
+=head1 VERSION
+
+Automatically generated by the Perl Swagger Codegen project: 
+
+=over 4 
+
+=item Build date: 2015-11-13T18:23:57.025Z
+
+=item Build package: class io.swagger.codegen.languages.PerlClientCodegen
+
+=item Codegen version: 
+
+=back
 
 =head2 A note on Moose
 
@@ -268,12 +297,13 @@ output formats are supported:
   -n           narrow format
   -p           POD format 
   -H           HTML format 
+  -m           Markdown format
   -h           print this help message
   -c           your application class
   
 The C<-c> option allows you to load and inspect your own application. A dummy
 namespace is used if you don't supply your own class.
-	
+
 =head1 DOCUMENTATION FROM THE SWAGGER SPEC
 
 Additional documentation for each class and method may be provided by the Swagger 
diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role/AutoDoc.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role/AutoDoc.pm
index 1b9886e1744..0dc30dbfb90 100644
--- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role/AutoDoc.pm
+++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role/AutoDoc.pm
@@ -28,11 +28,16 @@ sub _printisa {
 	my $sub =   join ', ', $meta->subclasses;
 	my $dsub =  join ', ', $meta->direct_subclasses;
 	
+    my $app_name = $self->version_info->{app_name};
+    my $app_version = $self->version_info->{app_version};
+    my $generated_date = $self->version_info->{generated_date};
+    my $generator_class = $self->version_info->{generator_class};
+
+    $~ = $how eq 'pod' ? 'INHERIT_POD' : 'INHERIT';
+    write;
+	
 	my ($rolepkg, $role_reqs);
 	
-	$~ = $how eq 'pod' ? 'INHERIT_POD' : 'INHERIT';
-	write;
-
 	foreach my $role (@roles) {
 		$rolepkg = $role->{package} || next; # some are anonymous, or something
 		next if $rolepkg eq 'WWW::SwaggerClient::Role::AutoDoc';
@@ -58,6 +63,14 @@ $myclass
                        $dsub
        All subclasses: @*
                        $sub
+                       
+           Target API: @* @*
+                       $app_name, $app_version
+         Generated on: @*
+                       $generated_date
+      Generator class: @* 
+                       $generator_class
+                       
 .
 	format ROLES =   
              Composes: ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
@@ -74,6 +87,26 @@ $myclass
 @*
 $myclass
 
+=head1 VERSION
+
+=head2 @* version: @*
+       $app_name,  $app_version
+       
+Automatically generated by the Perl Swagger Codegen project: 
+
+=over 4 
+
+=item Build date: @*
+                  $generated_date
+
+=item Build package: @*
+                     $generator_class
+
+=item Codegen version: 
+
+
+=back
+
 =head1 INHERITANCE
 
 =head2 Base class(es) 
@@ -90,6 +123,7 @@ $dsub
 
 @*
 $sub
+
                 
 =head1 COMPOSITION
 
@@ -171,6 +205,9 @@ sub _printmethod {
 		$original_pkg = $on; 
 		$doc = $original_pkg->method_documentation->{$delegate_to}->{summary};
 	}
+	else {
+	    $doc = $method->documentation;
+	}
 	
 	if ($how eq 'narrow') {
 		$~ = 'METHOD_NARROW';
@@ -302,7 +339,7 @@ sub _printattr {
 	my $from = $attr->associated_class->name || '';
 	my $reqd = $attr->is_required ? 'yes' : 'no';
 	my $lazy = $attr->is_lazy ? 'yes' : 'no';
-	my $has_doc = $attr->has_documentation ? 'yes' : 'no';
+	my $has_doc = $attr->has_documentation ? 'yes' : 'no'; # *_api attributes will never have doc, but other attributes might have
 	my $doc = $attr->documentation || '';
 	my $handles = join ', ', sort @{$attr->handles || []};
 	$handles ||= '';
diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/StoreApi.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/StoreApi.pm
index 70fd83317cb..21f9433fa32 100644
--- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/StoreApi.pm
+++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/StoreApi.pm
@@ -33,11 +33,6 @@ use WWW::SwaggerClient::Configuration;
 use base "Class::Data::Inheritable";
 
 __PACKAGE__->mk_classdata('method_documentation' => {});
-__PACKAGE__->mk_classdata('class_documentation' => {}); 
-
-__PACKAGE__->class_documentation({description => '',    # TODO
-                                  class => 'StoreApi',
-}                                 );
 
 sub new {
     my $class   = shift;
diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/UserApi.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/UserApi.pm
index 78a09f06138..a3cd164f3bc 100644
--- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/UserApi.pm
+++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/UserApi.pm
@@ -33,11 +33,6 @@ use WWW::SwaggerClient::Configuration;
 use base "Class::Data::Inheritable";
 
 __PACKAGE__->mk_classdata('method_documentation' => {});
-__PACKAGE__->mk_classdata('class_documentation' => {}); 
-
-__PACKAGE__->class_documentation({description => '',    # TODO
-                                  class => 'UserApi',
-}                                 );
 
 sub new {
     my $class   = shift;
diff --git a/samples/client/petstore/perl/t/04_role.t b/samples/client/petstore/perl/t/04_role.t
index 4a3d6ec13e8..73328fa6e62 100644
--- a/samples/client/petstore/perl/t/04_role.t
+++ b/samples/client/petstore/perl/t/04_role.t
@@ -1,4 +1,4 @@
-use Test::More tests => 38;
+use Test::More tests => 37;
 use Test::Exception;
 use Test::Warnings 'warnings';
 use Test::Deep;
@@ -15,8 +15,8 @@ SKIP: {
 		sub auth_setup_handler {}
 	";
 	
-	skip 'Moose not installed', 38 if $@;
-
+#	die $@ if $@;
+	skip 'Moose not installed', 37 if $@;
 
 my $api = MyApp->new;
 
@@ -48,9 +48,6 @@ is $get_pet->tags->[0]->id, '11', 'stored and retrieved: got the proper tag id';
 
 # documentation tests
 
-# API class docs 
-is $api->pet_api->class_documentation->{description}, '', 'got correct Pet API description'; # right now it's blank
-
 # API method docs 
 is_deeply(	[sort keys %{$api->pet_api->method_documentation}], 
 			[ 'add_pet', 'delete_pet', 'find_pets_by_status', 'find_pets_by_tags', 'get_pet_by_id', 'update_pet', 'update_pet_with_form', 'upload_file'],