Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Re: Coming up with good examples in POD

by perlfan (Vicar)
on Jul 25, 2020 at 23:05 UTC ( #11119807=note: print w/replies, xml ) Need Help??


in reply to Coming up with good examples in POD

> good examples in the synopsis

The SYNOPSIS is just that, a "quick start" or "tldr;" on how to get to something more interesting. It is not a treatise expounding on the inards of your functions.

Similarly, POD detailing the the methods is best written as "this is the intent of this function". It is not a full break down of the implementation and what constitutes it running successfully. This is what unit tests are for - and unit tests can also serve as excellent documentation themselves. If your goal is really to expound on the gritty details of a function or method, this is probly best done around the function it self. The code should be enough to describe what is happening. And if it isn't then a few well placed internal comments (behind the #) would work well.

Lastly, a good rule of thumb is that updating the code of a function should require documentation updates only in extreme cases (e.g., when IN/OUT changes, exceptions are added or removed, etc).

  • Comment on Re: Coming up with good examples in POD

Replies are listed 'Best First'.
Re^2: Coming up with good examples in POD
by Lady_Aleena (Curate) on Jul 28, 2020 at 06:01 UTC

    I may be missing something, but how is POD not for breaking down the implementations of a module and using it successfully? When I go to read how to use a module I have not seen before, I read the documentation of it. I have never looked at a module's unit tests to figure out how to use any module. I also do not look at the code searching for comments on usage either. Most of the time when I use a module, I do not even look at its code. (The few times I have looked at modules' code, I could not understand it, even metaphorically standing on my head.)

    One of my bigger problems using modules is that some make me play guessing games on how to use them. I have walked away from several modules because the documentation was lacking in examples of usage, or only showed the most common usages and ignored anything fringe. If I have to play guessing games when trying to use a module, I quit trying usually and roll my own code to get what I want.

    So, when I write the documentation for my modules, I want to come up with all the usages I can imagine and note them so users can see the full capabilities of what my modules can do. I do not want potential users to play guessing games on how to use what I wrote. I also do not want potential users to have to go on a treasure hunt (looking at the code and tests), to see how to use the module either.

    But as I said, I may be missing something.

    My OS is Debian 10 (Buster); my perl versions are 5.28.1 local and 5.16.3 or 5.30.0 on web host depending on the shebang.

    No matter how hysterical I get, my problems are not time sensitive. So, relax, have a cookie, and a very nice day!
    Lady Aleena
      I may be missing something, but how is POD not for breaking down the implementations of a module and using it successfully? When I go to read how to use a module I have not seen before, I read the documentation of it.

      POD (and user-facing documentation in general) is for describing the purpose and usage of modules and their functions. It is not, in general cases, for describing the internal ways the module achieves its ends as these are very rarely any concern of the user.

      For each function/sub/method one could reasonably expect the documentation to include:

      • function name
      • Arguments: types, names/positions, optional/mandatory, defaults, acceptable values
      • Return values: types, names/positions, flag values
      • Conditions which will throw exceptions
      • Prose describing the purpose, side-effects, caveats, context-sensitive matters, etc.
      • Example(s) showing how to call the function with suitable arguments, etc.

      In other words, everything to do with the purpose of the call and the interface to it. Everything else internal to the function does not need documenting here (eg. private variables, other functions it calls, etc.).


      🦛

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://11119807]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (6)
As of 2021-01-17 19:34 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Notices?