Re^3: Careful with Test::Pod::Coverage

Some tests are not there just to ensure that things are working, but rather to ensure the user that the author did take his time to do things properly.

Running a test doesn't say anything more than that the author managed to write code that produced output in the form:

    print 1..3
    ok 1
    ok 2
    ok 3
[download]

If you want to know the author did things properly, you'd run your tests, not the authors.

I, for one, enjoy seeing that the author took the time to make sure he was documenting every single function in his code.

I'd rather see a manual page that documents the API. Not every function belongs to the API - the more complex a functionality is that a module delivers, the lower the ratio of API functions vs total number of functions will be. Documenting functions belongs in source code comments. POD is user documentation.

Perl --((8:>*

Comment on Re^3: Careful with Test::Pod::Coverage Download Code

Replies are listed 'Best First'.
Re^4: Careful with Test::Pod::Coverage by tirwhan (Abbot) on Nov 14, 2005 at 11:11 UTC
Test::Pod::Coverage does ignore subroutines with names that start with an underscore, so if you use that particular convention you'll only have to document the subs that are part of the interface (i.e. not private). I agree wholeheartedly though, documentation of private functions does not belong in the pod, that's what comments are there for. Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. -- Brian W. Kernighan	[reply]
Re^4: Careful with Test::Pod::Coverage by demerphq (Chancellor) on Nov 14, 2005 at 11:37 UTC
`=begin apidoc =item _FooBar =end apidoc =cut` [download] Bit verbose but thats pod for you. Too bad there isn't a =finish directive that combined 'end X' with cut. Ie, `=finish apidoc` [download] would be a convenient shortcut for `=end apidoc =cut` [download] --- $world=~s/war/peace/g	[reply] [d/l] [select]