Updated the documentation

doc/advanced/testing.md

@@ -2,7 +2,7 @@
 When you will integrate this library with your own application, you will of course need to test it. Often we see developers get ahead of themselves, making a few trivial API calls with minimal values and drawing the wrong conclusions about Akismet's accuracy.
 
 ## Simulate a positive (spam) result
-Make a [comment check](../features/comment_check.md) API call with the `Author#name` set to `"viagra-test-123"` or `Author#email` set to `"akismet-guaranteed-spam@example.com"`. Populate all other required fields with typical values.
+Make a [comment check](../features/comment_check.md) API call with the `Author.name` set to `"viagra-test-123"` or `Author.email` set to `"akismet-guaranteed-spam@example.com"`. Populate all other required fields with typical values.
 
 The Akismet API will always return a `CheckResult.isSpam` response to a valid request with one of those values. If you receive anything else, something is wrong in your client, data, or communications.
 
@@ -13,14 +13,16 @@ async function main() {
   const author = new Author('127.0.0.1', 'Mozilla/5.0', {name: 'viagra-test-123'});
   const comment = new Comment(author, {content: 'A user comment'});
 
-  const client = new Client('123YourAPIKey', new Blog(new URL('https://www.yourblog.com')));
-  const isSpam = await client.checkComment(comment);
-  console.log(`It should be "true": ${isSpam}`);
+  const blog = new Blog(new URL('https://www.yourblog.com'));
+  const client = new Client('123YourAPIKey', blog);
+
+  const result = await client.checkComment(comment);
+  console.log(`It should be "CheckResult.isSpam": ${result}`);
 }
 ```
 
 ## Simulate a negative (not spam) result
-Make a [comment check](../features/comment_check.md) API call with the `Author#role` set to `"administrator"` and all other required fields populated with typical values.
+Make a [comment check](../features/comment_check.md) API call with the `Author.role` set to `"administrator"` and all other required fields populated with typical values.
 
 The Akismet API will always return a `CheckResult.isHam` response. Any other response indicates a data or communication problem.
 
@@ -31,29 +33,29 @@ async function main() {
   const author = new Author('127.0.0.1', 'Mozilla/5.0', {role: 'administrator'});
   const comment = new Comment(author, {content: 'A user comment'});
 
-  const client = new Client('123YourAPIKey', new Blog(new URL('https://www.yourblog.com')));
-  const isSpam = await client.checkComment(comment);
-  console.log(`It should be "false": ${isSpam}`);
+  const blog = new Blog(new URL('https://www.yourblog.com'));
+  const client = new Client('123YourAPIKey', blog);
+
+  const result = await client.checkComment(comment);
+  console.log(`It should be "CheckResult.isHam": ${result}`);
 }
 ```
 
 ## Automated testing
-Enable the `Client#isTest` option in your tests.
+Enable the `Client.isTest` option in your tests.
 
-That will tell Akismet not to change its behaviour based on those API calls – they will have no training effect. That means your tests will be somewhat repeatable, in the sense that one test won't influence subsequent calls.
+That will tell Akismet not to change its behaviour based on those API calls: they will have no training effect. That means your tests will be somewhat repeatable, in the sense that one test won't influence subsequent calls.
 
 ```js
 import {Author, Blog, Client, Comment} from '@cedx/akismet';
 
 async function main() {
   const author = new Author('127.0.0.1', 'Mozilla/5.0');
   const comment = new Comment(author, {content: 'A user comment'});
-  const client = new Client(
-    '123YourAPIKey',
-    new Blog(new URL('https://www.yourblog.com')),
-    {isTest: true}
-  );
-
+
+  const blog = new Blog(new URL('https://www.yourblog.com'));
+  const client = new Client('123YourAPIKey', blog, {isTest: true});
+
   console.log('It should not influence subsequent calls.');
   await client.checkComment(comment);
 }

doc/features/comment_check.md

@@ -1,5 +1,5 @@
 path: blob/master
-source: src/core/comment.ts
+source: src/comment.ts
 
 # Comment check
 This is the call you will make the most. It takes a number of arguments and characteristics about the submitted content
@@ -33,18 +33,18 @@ The exception `message` usually includes some debug information, provided by the
 ## Example
 
 ```js
-import {Author, Blog, Client, Comment} from '@cedx/akismet';
+import {Author, Blog, CheckResult, Client, Comment} from '@cedx/akismet';
 
 async function main() {
   try {
-    const comment = new Comment(
-      new Author('127.0.0.1', 'Mozilla/5.0'),
-      {content: 'A user comment', date: new Date}
-    );
-
-    const client = new Client('123YourAPIKey', new Blog(new URL('https://www.yourblog.com')));
-    const isSpam = await client.checkComment(comment);
-    console.log(isSpam ? 'The comment is spam' : 'The comment is ham');
+    const author = new Author('127.0.0.1', 'Mozilla/5.0');
+    const comment = new Comment(author, {content: 'A user comment', date: new Date});
+
+    const blog = new Blog(new URL('https://www.yourblog.com'));
+    const client = new Client('123YourAPIKey', blog);
+
+    const result = await client.checkComment(comment);
+    console.log(result == CheckResult.isHam ? 'The comment is ham.' : 'The comment is spam.');
   }
 
   catch (err) {

doc/features/key_verification.md

@@ -1,12 +1,19 @@
+path: blob/master
+source: src/client.ts
+
 # Key verification
-Key verification authenticates your key before calling the [comment check](comment_check.md), [submit spam](submit_spam.md), 
-or [submit ham](submit_ham.md) methods. This is the first call that you should make to Akismet and is especially useful
-if you will have multiple users with their own Akismet subscriptions using your application.
+Key verification authenticates your key before calling the [comment check](comment_check.md),
+[submit spam](submit_spam.md) or [submit ham](submit_ham.md) methods.
 
 ```
 Client.verifyKey(): Promise<boolean>
 ```
 
+This is the first call that you should make to Akismet and is especially useful
+if you will have multiple users with their own Akismet subscriptions using your application.
+
+See the [Akismet API documentation](https://akismet.com/development/api/#verify-key) for more information.
+
 ## Parameters
 None.
 
@@ -23,13 +30,17 @@ import {Blog, Client} from '@cedx/akismet';
 
 async function main() {
   try {
-    const client = new Client('123YourAPIKey', new Blog(new URL('https://www.yourblog.com')));
+    const blog = new Blog(new URL('https://www.yourblog.com'));
+    const client = new Client('123YourAPIKey', blog);
+
     const isValid = await client.verifyKey();
-    console.log(isValid ? 'The API key is valid' : 'The API key is invalid');
+    console.log(isValid ? 'The API key is valid.' : 'The API key is invalid.');
   }
 
   catch (err) {
     console.log(`An error occurred: ${err.message}`);
   }
 }
 ```
+
+See the [API reference](https://dev.belin.io/akismet.s/api) for detailed information about the `Client` and `Blog` classes, and their properties and methods.

doc/features/submit_ham.md

@@ -2,12 +2,14 @@
 This call is intended for the submission of false positives - items that were incorrectly classified as spam by Akismet.
 It takes identical arguments as [comment check](comment_check.md) and [submit spam](submit_spam.md).
 
+```
+Client.submitHam(comment: Comment): Promise<void>
+```
+
 Remember that, as explained in the [submit spam](submit_spam.md) documentation, you should ensure
 that any values you're passing here match up with the original and corresponding [comment check](comment_check.md) call.
 
-```
-Client.submitHam(comment: Comment): Promise
-```
+See the [Akismet API documentation](https://akismet.com/development/api/#submit-ham) for more information.
 
 ## Parameters
 
@@ -30,15 +32,16 @@ import {Author, Blog, Client, Comment} from '@cedx/akismet';
 
 async function main() {
   try {
-    const comment = new Comment(
-      new Author('127.0.0.1', 'Mozilla/5.0'),
-      {content: 'A valid user comment (ham)'}
-    );
+    const author = new Author('127.0.0.1', 'Mozilla/5.0');
+    const comment = new Comment(author, {content: 'A valid user comment (ham)'});
 
-    const client = new Client('123YourAPIKey', new Blog(new URL('https://www.yourblog.com')));
-    const isSpam = await client.checkComment(comment); // `true`, but `false` expected.
-
-    console.log('The comment was incorrectly classified as spam');
+    const blog = new Blog(new URL('https://www.yourblog.com'));
+    const client = new Client('123YourAPIKey', blog);
+
+    const result = await client.checkComment(comment);
+    // Got `CheckResult.isSpam`, but `CheckResult.isHam` expected.
+
+    console.log('The comment was incorrectly classified as spam.');
     await client.submitHam(comment);
   }
 

doc/features/submit_spam.md

@@ -1,15 +1,17 @@
 # Submit spam
 This call is for submitting comments that weren't marked as spam but should have been.
 
+```
+Client.submitSpam(comment: Comment): Promise<void>
+```
+
 It is very important that the values you submit with this call match those of your [comment check](comment_check.md) calls as closely as possible.
 In order to learn from its mistakes, Akismet needs to match your missed spam and false positive reports
 to the original [comment check](comment_check.md) API calls made when the content was first posted. While it is normal for less information
 to be available for [submit spam](submit_spam.md) and [submit ham](submit_ham.md) calls (most comment systems and forums will not store all metadata),
 you should ensure that the values that you do send match those of the original content.
 
-```
-Client.submitSpam(comment: Comment): Promise
-```
+See the [Akismet API documentation](https://akismet.com/development/api/#submit-spam) for more information.
 
 ## Parameters
 
@@ -32,15 +34,16 @@ import {Author, Blog, Client, Comment} from '@cedx/akismet';
 
 async function main() {
   try {
-    const comment = new Comment(
-      new Author('127.0.0.1', 'Mozilla/5.0'),
-      {content: 'An invalid user comment (spam)'}
-    );
+    const author = new Author('127.0.0.1', 'Mozilla/5.0');
+    const comment = new Comment(author, {content: 'An invalid user comment (spam)'});
+
+    const blog = new Blog(new URL('https://www.yourblog.com'));
+    const client = new Client('123YourAPIKey', blog);
 
-    const client = new Client('123YourAPIKey', new Blog(new URL('https://www.yourblog.com')));
-    const isSpam = await client.checkComment(comment); // `false`, but `true` expected.
+    const result = await client.checkComment(comment);
+    // Got `CheckResult.isHam`, but `CheckResult.isSpam` expected.
 
-    console.log('The comment was incorrectly classified as ham');
+    console.log('The comment was incorrectly classified as ham.');
     await client.submitSpam(comment);
   }