After I read the documentation, I head straight for code examples. A good CPAN distribution will have several tests, conventionally in the t directory. For example, on the JSON page, follow the MANIFEST link. I see roughly 50 test files. In these files, there are examples of how functions and methods are called (specific values passed to those functions), and examples of what is returned from functions. Some CPAN distributions have examples directories ("eg", "bin" etc.) which consist of short command line utilities for using the modules. Look at the source code itself. Sometimes authors embed helpful comments. If you want more examples of usage, try a Super Search. If you start using a module, and you find the POD inadequate, please submit specific enhancements via RT. CPAN is not just a spectator sport; you can participate too. If you include a patch, that increases the chances of the documentation being improved, not just for you, but for the whole community. Even if the patch is not applied by the author, the RT report is visible to everyone.

Never usually look in the files of the module. I just use 'em :-). Thanks for the advice! I'll try it. --perl.j

I'm just a practical programmer, but this is what I do. Read the perldoc which comes with the module, then look thru the module's source tree for directories or files with names like examples, cookbook, test, etc. In there you often will find many usages. If those come up empty, I google for it, like google perl Json.pm and you will find code samples. Module authors don't want to clutter their perldocs with too much example code, as it makes it harder to scan thru quickly. Plus many of them don't write English very well anyways. :-) I'm not really a human, but I play one on earth.

I'm not really a human, but I play one on earth. Old Perl Programmer Haiku ................... flash japh

Experiment, use Google, PerlMonks, StackOverflow, IRC channels... Once you understand the module, send patches to the author to improve the documentation.

Just use to_json() to go from perl to json, and from_json() to go from json to perl. Here's an example: use strict; use JSON; use Data::Dumper; # Here's some data my $data = { A => 1, B => "hello world", D => [ [ 'dog', 'cat', 'bird', ], [ 'red','green','blue'], ], D => { X => 1, Y => 2, } }; # print the data print Dumper($data), "

"; # convert perl data to json, then print out the json my $json = to_json($data); print "$json

"; # convert the json back to perl, then print it. # should be the same as before my $data2 = from_json($json); print Dumper($data2), "

"; [download]

If you need to look at the source code of a module, the author failed in writing their documentation. If Perl was C, it would be harder to not document your code since the parameters and return value can't be hidden. In Perl both are hidden. In writing docs, I basically address the following questions. What are the parameters?



how many?



variable parameters?



what parameter validation is performed?



how is error condition indicated? die/exceptions? warn? $!? return value?



What is the return value? list or scalar?



what are the possible errors (if possible, sometimes they come from something your module calls)?



common ways to leak resources



common mistakes



does undef as a parameter have special meaning?



what the function DOES NOT do



alternatives in same module, other modules or perl language



if XS and wrapping a C lib, situations that create unavoidable crashes or bugs in the C lib you as the module author hit

How does it not help much? I mean this as a sincere question, not to sound harsh or critisizing. I'm just wondering which part is causing you troubles. Read more... (2 kB)

I'm actually trying to send my JSON structure to Perl, and then have Perl send it to my DB. The problem is, I'm clueless, but that's a whole different thread. --perl.j

Well, at least you understand the nature of the problem, which in my experience means you're 80% of the way to a solution. :-) Many CPAN modules are quite poorly documented (and I'm including my own here). They often do a good job of listing the functions/methods defined by the module, with a brief description of what each function does, its inputs, its output, etc (we mostly have Test::Pod::Coverage to thank for that; without its existence CPAN documentation would be a lot worse); and they're usually quite good for boilerplate sections such as "here is the link to report bugs". The places they fall down is documenting why you might want to use the module in the first place (I suppose the assumption is that if you're reading the documentation, you've already made that decision); and fully worked practical examples of the use of the module, especially showing how it interacts with other commonly used modules. (For example, JSON could document how to interact with JSON RESTful APIs over the web using LWP::UserAgent; or how to manage collections of JSON on the file system using Path::Class.) There are fairly obvious reasons for this. If you're writing a module because you just need to get a job done, then you're probably concentrating more on doing the job than documenting it. Or if you're writing a module for fun; then documenting it is likely to be the least fun part. (And of course there are plenty of people for whom English is not their primary language, who find writing documentation in English especially difficult.) One overlooked area of documentation is the project's test files. These are Perl scripts (but with a ".t" suffix instead of ".pl") which show the software's intended behaviour. Invest some time in learning how Test::More works, and it will pay dividends - you'll be able to dive into a module's test cases and use them as extra documentation! If you do have any ideas for documentation for a CPAN module, submit it (in pod format) to the project's bug tracker. In most cases the author will be very happy to accept it - documentation provided this way is documentation he/she does not need to write himself/herself! Especially that sort of documentation about how and why to use a module in real-life tasks, which is so often overlooked. In cases of very extensive documentation, maybe format it into a separate document from the main module documentation. (e.g. for module Foo::Bar, write a Foo::Bar::Cookbook, Foo::Bar::Tutorial or Foo::Bar::FAQ document.) There ought to perhaps be a project that looks at the top 100 most important (by whatever metric) distributions on CPAN; identifies what they are missing in documentation; and writes it! That is, we should do for documentation, what Phalanx already did for test suites. Update: I've expanded upon this post in perldoc plus plus. perl -E'sub Monkey::do{say$_,for@_,do{($monkey=[caller(0)]->[3])=~s{::}{ }and$monkey}}"Monkey say"->Monkey::do'

Send it to Perl how? Through CGI? Over a socket? From a file? To the script's STDIN? Those all require a slightly different approach, but generally you'll eventually end up with the whole JSON data in a variable, let's say $json . Then you use one of the JSON decoding mechanisms - I'd go for the first one in the synopsis that seems to match the description, so you'd have a line like $perl_data_structure = decode_json $json; . Now, what $perl_data_structure looks like depends on what the outermost element of the JSON data was. Was it a map? Then $perl_data_structure will be a hash ref. Was it an array? Then $perl_data_structure will be an array ref. I am assuming you know what sort of data you want to send to your script and what it's formatted like, so this shouldn't be too much of an obstacle. Inserting it into a database, again, can't happen without asking yourself some questions, first. What do the tables in the database look like? What tables are there, what columns do they have and what data types go into those columns? Which elements from the incoming data do I want to insert? How do I transform the data structure into SQL -- but note that at this point you're no longer dealing with JSON. All you have is just an ordinary complex Perl data structure.

Don't forget that most modules have a test suite that can provide additional clues as to how a module may work. And some of the more complete distributions will contain an examples/ directory that contains some brief working examples. I wish more distributions did that.

Dave

Don't forget that most modules have a test suite that can provide additional clues as to how a module may work Test suites are supposed to be examples of usage ;)

The issue is, in my eyes, the documentation is poor. Poor how? Please stop reading now and write down how its poor, things you don't like, things that are missing, questions that are raised, questions that aren't answered. After you have a list of things reveal spoiler below Reveal this spoiler or all in this thread

If I find a Perl module's documentation obscure (either it's 'sparse' or I am), I may google something like the following: "use Data::Dumper" examples [download] Although I think the documentation for Data::Dumper is fine, I've encountered a lot of documentation that's not well written--in my opinion, of course. Writing good documentation is a skill that's separate and distinct from programming skills, and it requires that a programmer shift into being a teacher. Being a seasoned programmer doesn't mean being a good teacher.