in reply to Re^2: RFC - Documentation Review
in thread Please review documentation of my AI::Embedding module

"... 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:

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

Replies are listed 'Best First'.
Re^4: RFC - Documentation Review
by Bod (Parson) on Jun 04, 2023 at 22:10 UTC

    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]
      "... I didn't use export. ... Is that the same as export does?"

      export is a shell command that adds a variable and its value to your environment; this will be picked up by subsequent processes. You'll probably have a lot of variables in your environment already. Try these: 

      $ env | sort | less

$ perl -E 'say for sort keys %ENV' | less

      [download]

      Your author tests contain: 

      unless ( $ENV{RELEASE_TESTING} ) {
    plan( skip_all => "Author tests not required for installation" );
}

      [download]

      `export RELEASE_TESTING=1` results in $ENV{RELEASE_TESTING} having a TRUE value: your author tests will now be run.

      "I did it that way following the instructions in ..."

      Step 6 has: "Now you run all your tests ...".

      If you don't set RELEASE_TESTING to a TRUE value, all your tests will not be run.

      — Ken

[reply]
[d/l]
[select]
        export is a shell command that adds a variable and its value to your environment

        Ah!
        I'm on Windows, so it is set instead!

[reply]
[d/l]
Re^4: RFC - Documentation Review
by Bod (Parson) on Jun 04, 2023 at 22:20 UTC
    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 general, if you don't want to test something, change the test; don't change the code to avoid the test.

      See Test::Pod::Coverage. There's an example using also_private. There's also a link to Pod::Coverage with lots more examples of how to avoid needing to document subroutines.

      — Ken

[reply]
[d/l]
        In general, if you don't want to test something, change the test; don't change the code to avoid the test.

        Yes that makes sense.
        But in this case, your previous reply made me realise that test is a private * method and should be marked as such. It will also be removed when I have cured the bug which it is there to debug. So will not be in the production release of the module

        * private in the sense than only me and my test code will use it, not private in that it is only called from within the module.

[reply]
[d/l]

In Section Meditations