http://qs1969.pair.com?node_id=980247


in reply to Re: How to read CPAN documentation
in thread How to read CPAN documentation

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

Replies are listed 'Best First'.
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'
Re^3: How to read CPAN documentation
by Anonymous Monk on Jul 06, 2012 at 13:52 UTC
      ... and then, for OP's next career (or retirement), you can use the knowledge and skills that will take a major part of your lifetime to absorb to write the kind of sketchy documentation that only another long term, hard-core, CS-degree-holding, uber-geek can decipher.

      AnonyMonk's observation about reducing your need for the docs, "on a daily/weekly/monthly basis", could be read (admittedly, not as AM intended ) to suggest that there's a substantial amount of time required just to learn to read the docs en route to so mastering their content as to make them unnecessary.

      Sorry, while I agree that most of the links can be useful... and are responsive -- in a fashion -- to OP's original question, they set the price of learning the answer too high, IMO, for a learner with a specific project in hand.

      Here in the Monastery there have been several interesting discussions (for example, Re: A reasonable approach to getting a Perl skill foundation?) of aspects of this problem -- some from the POV of the developer, like the one cited, and some from the perspective of the learner ( check with Super Search ) and not a few that may seem merely tangential at first (cf: Re: The sourcecode *is* the documentation, isn't it? and 3 or 4 followups thereto).

        Your observation about reducing your need for the docs, "on a daily/weekly/monthly basis", could be read (admittedly, not as you intended ) to suggest that there's a substantial amount of time required just to learn to read the docs en route to so mastering their content as to make them unnecessary.

        Sure, if you're purposefully trying to read between the lines

        Sorry, while I agree that most of the links can be useful... and are responsive -- in a fashion

        Well, that is how you become a seasoned programmer, so you can just go on CPAN and pick it up in no time

        -- to OP's original question, they set the price of learning the answer too high, IMO, for a learner with a specific project in hand.

        If you think so, why don't you lower the price?

        perl.j has history of both generic and specific questions, he knows how to SOPW, he wasn't asking for help with a project, he merely alluded to it.

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.