[#225] Clean up code comments and mocks (#226)

Make use of Jest's automocking for automatically mocking the whole
`client` module with `jest.mock`. This automatically sets all exports of
the module to mock functions (jest.fn()).

Align the module level documentation to use multi-line comments.

[closes #225]

src/common/adapters/github.js

@@ -1,8 +1,18 @@
+/**
+ * GitHub and GitHub Enterprise adapter
+ *
+ * The adapter uses the DOM to extract ticket information from issues.
+ */
+
 import { $all, $has, $text, $value } from './helpers';
 
-// Element classes on GitHub have slightly changed over time.
-// To maintain support for some older GitHub Enterprise instances,
-// the adapter will attempt different versions of selectors.
+/**
+ * DOM selectors
+ *
+ * Element classes on GitHub have slightly changed over time.
+ * To maintain support for some older GitHub Enterprise instances, the adapter
+ * will attempt different versions of selectors.
+ */
 export const selectors = {
   default: {
     issuesPage: '.js-check-all-container .js-issue-row.selected',

src/common/adapters/gitlab.js

@@ -1,3 +1,9 @@
+/**
+ * Gitlab adapter
+ *
+ * The adapter uses the DOM to extract information about tickets.
+ */
+
 import { $has, $text } from './helpers';
 
 async function scan(loc, doc) {

src/common/adapters/jira.js

@@ -1,13 +1,16 @@
-// Jira adapter
-//
-// This adapter extracts the identifier of the selected issue from the page URL
-// and uses the Jira API to retrieve the corresponding ticket information.
-//
-// https://developer.atlassian.com/server/jira/platform/rest-apis/
-//
-// * Backlog and Active Sprints: https://<YOUR-SUBDOMAIN>.atlassian.net/secure/RapidBoard.jspa?…&selectedIssue=<ISSUE-KEY>
-// * Issues and filters: https://<YOUR-SUBDOMAIN>.atlassian.net/projects/<PROJECT-KEY>/issues/<ISSUE-KEY>
-// * Issue view: https://<YOUR-SUBDOMAIN>.atlassian.net/browse/<ISSUE-KEY>
+/**
+ * Jira adapter
+ *
+ * The adapter extracts the identifier of the selected issue from the page URL
+ * and uses the Jira API to retrieve the corresponding ticket information.
+ *
+ * https://developer.atlassian.com/server/jira/platform/rest-apis/
+ *
+ * Supported page URLs:
+ * - Backlog and Active Sprints: https://<YOUR-SUBDOMAIN>.atlassian.net/secure/RapidBoard.jspa?…&selectedIssue=<ISSUE-KEY>
+ * - Issues and filters: https://<YOUR-SUBDOMAIN>.atlassian.net/projects/<PROJECT-KEY>/issues/<ISSUE-KEY>
+ * - Issue view: https://<YOUR-SUBDOMAIN>.atlassian.net/browse/<ISSUE-KEY>
+ */
 
 import { match } from 'micro-match';
 

src/common/adapters/jira.test.js

@@ -4,7 +4,7 @@ import client from '../client';
 import loc from './__helpers__/location';
 import scan from './jira';
 
-jest.mock('../client', () => jest.fn());
+jest.mock('../client');
 
 const key = 'RC-654';
 

src/common/adapters/notion.test.js

@@ -2,7 +2,7 @@ import client from '../client';
 import loc from './__helpers__/location';
 import scan from './notion';
 
-jest.mock('../client', () => jest.fn());
+jest.mock('../client');
 
 describe('notion adapter', () => {
   const id = '5b1d7dd7-9107-4890-b2ec-83175b8eda83';

src/common/adapters/trello.js

@@ -1,12 +1,14 @@
-// Trello adapter
-//
-// This adapter extracts the identifier of the selected card (short link) from
-// the page URL and uses the Trello API to retrieve the corresponding card
-// information.
-//
-// https://developers.trello.com/v1.0/reference#introduction
-//
-// Card view: https://trello.com/c/<SHORT-LINK>/1-ticket-title
+/**
+ * Trello adapter
+ *
+ * The adapter extracts the identifier of the selected card (short link) from
+ * the page URL and uses the Trello API to retrieve the corresponding card
+ * information.
+ *
+ * https://developers.trello.com/v1.0/reference#introduction
+ *
+ * Card view: https://trello.com/c/<SHORT-LINK>/1-ticket-title
+ */
 
 import { match } from 'micro-match';
 

src/common/adapters/trello.test.js

@@ -2,7 +2,7 @@ import client from '../client';
 import loc from './__helpers__/location';
 import scan from './trello';
 
-jest.mock('../client', () => jest.fn());
+jest.mock('../client');
 
 const key = 'haKn65Sy';