Skip to content

Documentation is wrong/misleading #271

@tyrrminal

Description

@tyrrminal
  • JSON::Validator version: 5.14
  • Perl version: 5.38
  • Operating system: Debian 12.1

Steps to reproduce the behavior

In an attempt to diagnose an issue I was seeing in my app (which turned out to be the fourth item below), I stumbled across what seem to be some errors in the documentation.

  1. JSON::Validator::Joi POD->SYNOPSIS: the schema declaration for the email field does not include ->string causing it to default to object, so testing the sample code does not work as expected.
  2. JSON::Validator::Joi POD->SYNOPSIS: the data value for the email field should be 'jhthorsen@cpan.org' not "jhthorsen@cpan.org"
  3. JSON::Validator POD->SYNOPSIS: In the "Using Joi" section, if the code under "joi() can also validate directly" is run as written, it results in the @errors array containing a JSON::Validator::Joi object rather than any JSON::Validator::Error objects. As there is no corroborating documentation for the joi() function, I'm unsure whether this is a bug in the code, or just incorrect documentation.
  4. JSON::Validator POD->SYNPOSIS: in the "Using Joi" section under "Use joi() to build the schema", the code will partially function, but without adding ->compile, some errors (like those related to the required and strict attributes) won't be output

Expected behavior

  1. No validation errors (unless the point of this section is to demonstrate such a validation error, in which case that should be specifically called out)
  2. No errors
  3. The @errors array should contain /age: -42 < minimum(0) (JSON::Validator::Error)
  4. The expectation is that everything stated in the code would be validated, if ->validate were to be called (though as the documentation is written, it is not)

Actual behavior

  1. /email: Expected object - got string. (JSON::Validator::Error)
  2. Global symbol "@cpan" requires explicit package name (did you forget to declare "my @cpan"?)
  3. The @errors array contains only a JSON::Validator::Joi object
  4. Provided that the code was extrapolated into a complete "thought," the required attribute would be ignored, resulting in validation errors not being produced when they should be.

Metadata

Metadata

Assignees

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions