Documentation improvements

Changes

@@ -3,7 +3,8 @@ Revision history for Whelk
 {{$NEXT}}
 	- Default and example values are now validated before they are put into OpenAPI document
 	- Typo detection now suggests a closest valid alternative if one exists
-	- Refactored Whelk::OpenAPI
+	- Whelk::OpenAPI has been refactored
+	- Added documentation for Whelk::Exception
 	- Set minimum YAML::PP version
 
 0.03 - 2024-07-04

lib/Whelk/Exception.pm

@@ -7,3 +7,43 @@ attr -hint => undef;
 
 1;
 
+__END__
+
+=pod
+
+=head1 NAME
+
+Whelk::Exception - Exceptions for your API
+
+=head1 SYNOPSIS
+
+	use Whelk::Exception;
+
+	# will set the status and log the body as error. A stock error message will
+	# be used in the response.
+	Whelk::Exception->throw(400, body => 'weird request got rejected because of reasons');
+
+	# no log will be created, but the hint will be returned in the API response
+	Whelk::Exception->throw(403, hint => 'Access denied, not authorized');
+
+	# fatal API error, will not return an API error page but rather regular text / html error page
+	Kelp::Exception->throw(500, body => 'Something went very, very wrong');
+
+=head1 DESCRIPTION
+
+Whelk::Exception is a tiny subclass of L<Kelp::Exception>. It introduces a
+L</hint> attribute, which can be set to let the user know more about the error.
+Much like Kelp exceptions, only 4XX and 5XX statuses are allowed.
+
+Whelk will treat Whelk::Exception differently than Kelp::Exception. Whelk
+exceptions will be treated as planned API events and returned in API format.
+Kelp exceptions will be thrown again, letting the Kelp application handle them,
+which will result in plaintext or html error pages.
+
+=head1 ATTRIBUTES
+
+=head2 hint
+
+This is a hint for the API user. It must be a string and will be put into the
+error response as-is. It will not be logged.
+

lib/Whelk/Manual.pod

@@ -8,10 +8,8 @@ Whelk::Manual - Reference to APIs with Whelk
 
 =head1 SYNOPSIS
 
+	# File: conf/whelk_config.pl
 	##############################
-	# File: conf/whelk_config.pl #
-	##############################
-
 	{
 		resources => {
 			'MyApi' => {
@@ -35,10 +33,8 @@ Whelk::Manual - Reference to APIs with Whelk
 		},
 	}
 
+	# File: lib/Whelk/Resource/MyApi.pm
 	#####################################
-	# File: lib/Whelk/Resource/MyApi.pm #
-	#####################################
-
 	package Whelk::Resource::MyApi;
 
 	use Kelp::Base 'Whelk::Resource';
@@ -91,10 +87,8 @@ Whelk::Manual - Reference to APIs with Whelk
 		];
 	}
 
+	# File: app.psgi
 	##################
-	# File: app.psgi #
-	##################
-
 	use Kelp::Base -strict;
 	use Whelk;
 	use lib 'lib';
@@ -127,6 +121,14 @@ an afterthought in Whelk, but rather welded into its very core. Each time you
 declare how your data should look, it serve both as documentation through
 OpenAPI as well as runtime validation scheme.
 
+Whelk is designed to be dead-easy but hard to misuse. Even though all the
+configuration is in form of plain Perl hashes, most of them are immediately
+translated to internal objects with built-in typo detection on construction.
+Even the data you return from the endpoint subroutine may get rejected if it
+does not conform with the declared schema. You don't have to learn the ins and
+outs of a fancy DSL language to use it efficiently, but it's extremely easy to
+come up with your own to help you build the required hashes.
+
 Data types are defined in Whelk's own format, very similar to JSON schema but
 simpler and not as strict when it comes to validation. Reusable, named schemas
 can be created and easily referenced or extended. These named definitions are

lib/Whelk/Manual/Kelp.pod

@@ -8,10 +8,8 @@ Whelk::Manual::Kelp - Setting up Whelk inside Kelp
 
 =head1 SYNOPSIS
 
+	# File: conf/config.pl
 	########################
-	# File: conf/config.pl #
-	########################
-
 	{
 		modules => [qw(JSON YAML Whelk)],
 		modules_init => {
@@ -28,8 +26,7 @@ Whelk::Manual::Kelp - Setting up Whelk inside Kelp
 		},
 	}
 
-	######################
-	# File: lib/MyApp.pm #
+	# File: lib/MyApp.pm
 	######################
 	package MyApp;
 
@@ -41,17 +38,14 @@ Whelk::Manual::Kelp - Setting up Whelk inside Kelp
 		$self->whelk->init;
 	}
 
-	#################################
-	# File: lib/MyApp/Controller.pm #
+	# File: lib/MyApp/Controller.pm
 	#################################
 	package MyApp::Controller;
 
 	use Kelp::Base 'MyApp';
 
+	# File: lib/MyApp/Controller/Res.pm
 	#####################################
-	# File: lib/MyApp/Controller/Res.pm #
-	#####################################
-
 	package MyApp::Controller::Res;
 
 	use Kelp::Base 'MyApp::Controller';
@@ -101,7 +95,7 @@ your app.
 
 Each controller which is supposed to be a Whelk resource must consume
 C<Whelk::Role::Resource> (L<Role::Tiny> role). It can be done with C<with> from
-C<Role::Tiny::With> or C<Moo>.
+L<Role::Tiny::With> or L<Moo>.
 
 Don't consume this role in your base controller, unless you plan to have all
 controllers as Whelk resources.