Documentation and error improvements

[jpepersack]

The examples in the documentation are completely useless unless the user had a deep understanding of the low-level AWS API. Even then you have to constantly switch back and forth between the API documentation and the Perldoc and try to divine the mapping between them. Concrete examples are necessary for all methods, not abstract meta-examples.

For instance for Paws::DynamoDB::CreateTable, give an actual, executable concrete example how to create a table. For PutItem, actually show how to put an item into the table you just created.

The documentation as written is unusable and the error messages are nearly impossible to decypher.

[maneta]

Hi Joe,

Probably we could blame the Auto Generated Documentation. Actually Paws has lots of auto generated stuff. We are trying to create a "task force" to get a human touch in the documentation. All help we can get is welcome.

Hope you understand.

[pplu]

Hi Joe,

I'm sorry to hear that the documentation is not good for you. As @maneta points out, this is because documentation is coming from AWS definition files. Keep in mind that this is not an official SDK, and it's 100% community driven. Creating the documentation you propose would take a gigantic effort, but I'd love to see an example of the documentation you would expect, to see if we can make the documentation better, while it being autogenerated (or at least little pieces hand-written).

Please report some of the error messages you've had trouble with, and tell us how they were not helpful to you. We'll see how we can make them better.

Also, we have an examples/ directory with some scripts that do random things with services. For dynamodb, for example, you have a fully working example that creates a table, puts an object, and then retrieves it: https://github.com/pplu/aws-sdk-perl/blob/master/examples/dynamodb.pl. Hope it helps :smile:

[castaway]

I'm being sponsored by ZipRecruiter to have a go at improving some of the Paws generated documentation. This is one of the items on my list.

I'd like to start by improving the short and generic example given in the callclass documentation, using the data we already have about the names and attributes of the call arguments. Ideally this will be turned into a synopsis for each call that can be copied into the user's code, with just the arguments needing to be changed.

This: $service_obj->CreateBucket(Att1 => $value1, Att2 => $value2, ...);

Would change to something like: my $s3 = Paws->service('S3');

$s3->CreateBucket( Bucket => 'MyBucket', ACL => 'private', CreateBucketConfiguration => { LocationConstraint => 'somewhere' }, );

[pplu]

Paws 0.37 with changes around the documentation has just been uploaded to CPAN