in reply to Please review documentation of my AI::Embedding module

G'day Bod,

I always start my POD with: 

=encoding utf8

[download]

It's part of my template for module code so I don't have to do anything manually to get this. See "perlpod: =encoding encodingname" if you're unfamiliar with this POD command.

"... under the same terms as the Perl 5 programming language system itself."

This looks strained (for want of a better word). I'd remove the word "system"; and consider whether I even want "itself".

"Why is it you only find typos after publishing?"

Checking your own work is not the best idea because your brain already knows what you meant and that's what it tends to see. However, if you're like me, you don't have the benefit of a proof-reader on hand. I generally try to read POD in different contexts:

Each of those will likely provide a slightly different view; typos will tend to be more prominent. Changing the width of your screen may also give a different view; I can never be bothered to go to that much effort.

I see you have 't/pod.t' with Test::Pod which should pick up typos in POD commands (e.g. =begun); and 't/pod-coverage.t' with Test::Pod::Coverage which should pick up typos in subroutine names. However, these are set up as "Author tests" and, from "Test::More fails...", you don't seem to be running these: 

t/manifest.t ...... skipped: Author tests not required for installatio
+n
t/pod-coverage.t .. skipped: Author tests not required for installatio
+n
t/pod.t ........... skipped: Author tests not required for installatio
+n

[download]

Those are messages for users installing your module; you should do `export RELEASE_TESTING=1` before your `make test` (or similar; e.g. I see gmake test in that post).

In addition, there are other Test::Pod::* modules which you may find helpful. I don't use any of these, so I'll make no recommendations, but I see some for checking spelling, links, and so on. Search for these from MetaCPAN.

— Ken

Replies are listed 'Best First'.
Re^2: RFC - Documentation Review
by Bod (Parson) on Jun 03, 2023 at 11:23 UTC
    >> "... under the same terms as the Perl 5 programming language system itself."
     
    This looks strained (for want of a better word). I'd remove the word "system"; and consider whether I even want "itself".

    Good point...
    I wasn't sure if changing the wording of licence agreements was a good idea as I have no idea how much "legal rigour" they have been subjected to. I didn't write that but rather chose it from the options available within Module::Starter

    I see you have 't/pod.t' with Test::Pod which should pick up typos

    I noticed those as well but haven't touched them as I don't understand them and note that publishing the module works without altering them. Again, they were added by Module::Starter.

    First, I want to get the module published, available and usable...then I will (hopefully) get a better understanding of how I can improve the details and the system for creating and publishing modules so that future ones will be better.

    Seems like the POD tests need to be looked at first :)

[reply]
[d/l]
[select]
      "... haven't touched them as I don't understand them and note that publishing the module works without altering them."

      You should run all of your tests and ensure they pass before even thinking about publishing. If you don't understand them, read the documentation: Test::Pod & Test::Pod::Coverage. If you don't understand the documentation, ask us — you would be fully aware that we're more than happy to help.

      I downloaded the tarball from the "Here is the documentation" link, https://metacpan.org/release/BOD/AI-Embedding-0.1_2/view/lib/AI/Embedding.pm, that you provided in your OP: "https://cpan.metacpan.org/authors/id/B/BO/BOD/AI-Embedding-0.1_2.tar.gz". I set up a directory for testing, then unpacked the tarball, giving: 

      ken@titan ~/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2
$ ls -al
total 23
drwxr-xr-x 1 ken None    0 Jun  2 22:14 .
drwxr-xr-x 1 ken None    0 Jun  3 09:14 ..
-rw-r--r-- 1 ken None  425 Jun  2 21:54 Changes
drwxr-xr-x 1 ken None    0 Jun  2 22:15 lib
-rw-r--r-- 1 ken None 1819 Jun  2 21:50 Makefile.PL
-rw-r--r-- 1 ken None  304 Jun  2 22:14 MANIFEST
-rw-r--r-- 1 ken None 1169 Jun  2 22:14 META.json
-rw-r--r-- 1 ken None  675 Jun  2 22:14 META.yml
-rw-r--r-- 1 ken None 1353 May 30 20:54 README
drwxr-xr-x 1 ken None    0 Jun  2 22:14 t

      [download]

      Those are the files you should have in front of you (albeit in a different parent directory). Here's what you should do: 

      ken@titan ~/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2
$ perl Makefile.PL
Checking if your kit is complete...
Looks good
Generating a Unix-style Makefile
Writing Makefile for AI::Embedding
Writing MYMETA.yml and MYMETA.json

ken@titan ~/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2
$ make
cp lib/AI/Embedding.pm blib/lib/AI/Embedding.pm
Manifying 1 pod document

ken@titan ~/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2
$ export RELEASE_TESTING=1

ken@titan ~/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2
$ make test
PERL_DL_NONLAZY=1 "/home/ken/perl5/perlbrew/perls/perl-5.36.0/bin/perl
+.exe" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::
+Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ....... Use of uninitialized value in concatenation (.) or
+ string at /home/ken/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2/blib
+/lib/AI/Embedding.pm line 59.
t/00-load.t ....... 1/1 # Testing AI::Embedding 0.12, Perl 5.036000, /
+home/ken/perl5/perlbrew/perls/perl-5.36.0/bin/perl
t/00-load.t ....... ok
t/manifest.t ...... skipped: Test::CheckManifest 0.9 required
t/pod-coverage.t .. Use of uninitialized value in concatenation (.) or
+ string at /home/ken/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2/blib
+/lib/AI/Embedding.pm line 59.
t/pod-coverage.t .. 1/1
#   Failed test 'Pod coverage on AI::Embedding'
#   at /home/ken/perl5/perlbrew/perls/perl-5.36.0/lib/site_perl/5.36.0
+/Test/Pod/Coverage.pm line 133.
# Coverage for AI::Embedding is 77.8%, with 2 naked subroutines:
#       test
#       test_embedding
# Looks like you failed 1 test of 1.
t/pod-coverage.t .. Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/1 subtests
t/pod.t ........... ok

Test Summary Report
-------------------
t/pod-coverage.t (Wstat: 256 (exited 1) Tests: 1 Failed: 1)
  Failed test:  1
  Non-zero exit status: 1
Files=4, Tests=3,  1 wallclock secs ( 0.05 usr  0.01 sys +  0.36 cusr 
+ 0.39 csys =  0.81 CPU)
Result: FAIL
Failed 1/4 test programs. 1/3 subtests failed.
make: *** [Makefile:857: test_dynamic] Error 255

      [download]

      I'm running Perl v5.36.0; I pretty sure that has nothing to do with any of your test failures. Here's points regarding those problems:

      • t/00-load.t: Fix the code such that you don't get that warning. `make test` might not care about that; but you should.
      • t/manifest.t: I didn't have Test::CheckManifest installed so the test is skipped. I'll get back to that; see below.
      • t/pod-coverage.t:
        • When you fix t/00-load.t, you'll have fixed the same warning here.
        • You have two subroutines in your module, test & test_embedding, which are not documented in your POD: add appropriate documentation.

      Test::CheckManifest — I've had no end of problems with this module. Just to demonstrate, I installed it and reran `make install`: 

      ken@titan ~/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2
$ make test
PERL_DL_NONLAZY=1 "/home/ken/perl5/perlbrew/perls/perl-5.36.0/bin/perl
+.exe" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::
+Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ....... Use of uninitialized value in concatenation (.) or
+ string at /home/ken/tmp/pm_11152618_rfc_doco/AI-Embedding-0.1_2/blib
+/lib/AI/Embedding.pm line 59.
t/00-load.t ....... 1/1 # Testing AI::Embedding 0.12, Perl 5.036000, /
+home/ken/perl5/perlbrew/perls/perl-5.36.0/bin/perl
t/00-load.t ....... ok
t/manifest.t ...... Bailout called.  Further testing stopped:  Cannot 
+find a MANIFEST. Please check!
t/manifest.t ...... Dubious, test returned 255 (wstat 65280, 0xff00)
Failed 1/1 subtests
FAILED--Further testing stopped: Cannot find a MANIFEST. Please check!
make: *** [Makefile:857: test_dynamic] Error 255

      [download]

      I gave up on this module some years ago and instead use what it suggests in "Test::CheckManifest - REPLACE THIS MODULE". I use more descriptive test names: 

      is_deeply([manicheck()], [], 'Check files in "MANIFEST" exist.');
is_deeply([filecheck()], [], 'Check for files not in "MANIFEST" or "MA
+NIFEST.SKIP".');

      [download]
      "Again, they were added by Module::Starter."

      You are under no obligation to use that directly. I use Module::Starter::PBP as a plugin. Here's my config: 

      $ cat ~/.module-starter/config
author:  Ken Cotterill
email:   kcott@cpan.org
builder: ExtUtils::MakeMaker
plugins: Module::Starter::PBP
template_dir: /home/ken/.module-starter/P536

      [download]

      I have multiple directories under /home/ken/.module-starter/ for different Perl versions and different types of modules; P536 is for Perl v5.36.0 templates.

      Depending on what you decide after receiving advice on "How Critical is Critic?", this plugin may be useful in that respect. I don't use it for that purpose. What I like is the ability to customise the templates; I'm no longer locked in to what Module::Starter provides. Consider the hoops you had to jump through when dealing with "CPAN Ratings..."; you could have just made a text change to your own template; I acknowledge that was a good learning exercise with respect to GitHub.

      — Ken

[reply]
[d/l]
[select]

        Thank you for the amazingly complete answer as usual Ken

        Those are the files you should have in front of you (albeit in a different parent directory). Here's what you should do

        That is indeed what I have :)

        However, I didn't use export. Instead I used make, make test followed by make disttest. After that, I copied the two META files from the test path to the root directory.
        Is that the same as export does?

        I did it that way following the instructions in Re: What do I use to release a module to CPAN for the first time?

        You have two subroutines in your module, test & test_embedding, which are not documented in your POD: add appropriate documentation

        As I said in the original question, the second raw_embedding in the documentation is actually test_embedding. So the documentation exists for this.

        I am having problems getting a private method working and test is a method to...erm...test it... It doesn't matter until multiple API providers are added so I've decided to leave that problem for now and get the module released. Then I will come back to solving the bug which will probably be yet another question for The Monastery!

        You are under no obligation to use that directly

        Ah! That's a relief...
        I was considering looking for an alternative to Module::Starter (another question!) but perhaps I don't need to after all.

[reply]
[d/l]
[select]
        You have two subroutines in your module, test & test_embedding, which are not documented in your POD

        I've renamed the temporary method from test to _test so the POD tests shouldn't worry about it...

[reply]
[d/l]
[select]

In Section Meditations