How to read CPAN documentation

perl.j has asked for the wisdom of the Perl Monks concerning the following question:

Replies are listed 'Best First'.
Re: How to read CPAN documentation (code) by toolic (Bishop) on Jul 06, 2012 at 13:04 UTC
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.	[reply] [d/l]
Re^2: How to read CPAN documentation (code) by perl.j (Pilgrim) on Jul 06, 2012 at 13:35 UTC
Never usually look in the files of the module. I just use 'em :-). Thanks for the advice! I'll try it. --perl.j	[reply]
Re: How to read CPAN documentation by zentara (Archbishop) on Jul 06, 2012 at 13:15 UTC
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. Old Perl Programmer Haiku ................... flash japh	[reply]
Re: How to read CPAN documentation by choroba (Cardinal) on Jul 06, 2012 at 12:06 UTC
Experiment, use Google, PerlMonks, StackOverflow, IRC channels... Once you understand the module, send patches to the author to improve the documentation.	[reply]
Re: How to read CPAN documentation by scorpio17 (Canon) on Jul 06, 2012 at 13:15 UTC
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), "\n"; # convert perl data to json, then print out the json my $json = to_json($data); print "$json\n"; # convert the json back to perl, then print it. # should be the same as before my $data2 = from_json($json); print Dumper($data2), "\n";` [download]	[reply] [d/l]
Re: How to read CPAN documentation by bulk88 (Priest) on Jul 06, 2012 at 16:39 UTC
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	[reply]
Re: How to read CPAN documentation by muba (Priest) on Jul 06, 2012 at 12:09 UTC
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)	[reply]
Re^2: How to read CPAN documentation by perl.j (Pilgrim) on Jul 06, 2012 at 12:12 UTC
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	[reply]
Re^3: How to read CPAN documentation by tobyink (Canon) on Jul 06, 2012 at 13:29 UTC
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'`	[reply]
Re^3: How to read CPAN documentation by Anonymous Monk on Jul 06, 2012 at 13:52 UTC
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. Actually it isn't :) read below So, my question to you is, how can I become better at reading CPAN module documentation, and understanding how to use modules that don't come with books or tutorials in them? Become a seasoned Perl programmer -- increase your experience, increase your vocabulary, write and read more code (perl and not perl), read more operating system documentation, learn more about computers Forget the synopsis and go straight for the MANIFEST, for example http://search.cpan.org/dist/CGI/MANIFEST, http://search.cpan.org/dist/JSON/MANIFEST, http://search.cpan.org/dist/Pod-Simple/MANIFEST Read The Art of Unix Programming Read What are the most basic, generic aspects of programming? / How to Design Programs Tutorials: Input and Output / beginning-perl 3145_Chap06.pdf Files and Data perlvar#@ARGV? perlvar#STDIN? JSON#HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER Tutorials->Database Programming->DBI recipes perlunitut: Unicode in Perl#I/O flow (the actual 5 minute tutorial) A UTF8 round trip with MySQL, http://search.cpan.org/perldoc/DBD::SQLite#sqlite_unicode With enough practice/work, you don't have to keep referencing the docs on a daily/weekly/monthly basis, these things becomes part of your vocabulary/daily speech/thoughts. With enough practice you're seasoned.	[reply]
Re^4: How to read CPAN documentation by ww (Archbishop) on Jul 06, 2012 at 14:25 UTC
Re^5: How to read CPAN documentation by Anonymous Monk on Jul 06, 2012 at 14:47 UTC
Re^3: How to read CPAN documentation by muba (Priest) on Jul 06, 2012 at 17:33 UTC
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.	[reply] [d/l] [select]
Re: How to read CPAN documentation by davido (Cardinal) on Jul 06, 2012 at 18:57 UTC
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	[reply] [d/l]
Re^2: How to read CPAN documentation by Anonymous Monk on Jul 06, 2012 at 19:07 UTC
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 ;)	[reply]
Re: How to read CPAN documentation by Anonymous Monk on Jul 06, 2012 at 13:39 UTC
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>	[reply]
Re: How to read CPAN documentation by Kenosis (Priest) on Jul 06, 2012 at 16:56 UTC
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.	[reply] [d/l] [select]
Re: How to read CPAN documentation by TomDLux (Vicar) on Jul 06, 2012 at 17:30 UTC
I agree totally. I've ocassionally looked at a module with an interesting name, let's say Fnord.pm, but there's no reference to what Fnording is. There's an explanation of how to invoke routines, but no mention of why, of what problem this modeule's services will solve. As Occam said: Entia non sunt multiplicanda praeter necessitatem.	[reply]


Perl-Sensitive Sunglasses
	PerlMonks