Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Re^2: RFC - Documentation Review

by Bod (Parson)
on Jun 03, 2023 at 11:23 UTC ( [id://11152627]=note: print w/replies, xml ) Need Help??


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

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

Replies are listed 'Best First'.
Re^3: RFC - Documentation Review
by kcott (Archbishop) on Jun 03, 2023 at 19:08 UTC
    "... 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

    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

    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

    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".');
    "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

    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

      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.

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

        Your author tests contain:

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

        `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

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

        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

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others wandering the Monastery: (5)
As of 2024-03-28 23:29 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found