Improve several test descriptions

Address PR feedback by rewriting several test descriptions and adding
comments.

src/annotator/components/test/toolbar-test.js

@@ -24,12 +24,13 @@ describe('Toolbar', () => {
   const findButton = (wrapper, label) =>
     wrapper.find(`button[title="${label}"]`);
 
-  it('renders nothing if `useMinimalControls` is true and the sidebar is closed', () => {
+  context('when `useMinimalControls` is true', () => {
+    it('renders nothing if the sidebar is closed', () => {
       const wrapper = createToolbar({ useMinimalControls: true });
       assert.isFalse(wrapper.find('button').exists());
     });
 
-  it('renders only the Close button if `useMinimalControls` is true', () => {
+    it('renders only the "Close" button if the sidebar is open', () => {
       const wrapper = createToolbar({
         useMinimalControls: true,
         isSidebarOpen: true,
@@ -37,6 +38,7 @@ describe('Toolbar', () => {
       assert.equal(wrapper.find('button').length, 1);
       assert.isTrue(findButton(wrapper, 'Close annotation sidebar').exists());
     });
+  });
 
   it('renders the normal controls if `useMinimalControls` is false', () => {
     const wrapper = createToolbar({ useMinimalControls: false });

src/annotator/components/toolbar.js

@@ -11,6 +11,8 @@ function ToolbarButton({
   selected,
 }) {
   const handleClick = event => {
+    // Stop event from propagating up to the document and being treated as a
+    // click on document content, causing the sidebar to close.
     event.stopPropagation();
     onClick();
   };
@@ -103,7 +105,11 @@ Toolbar.propTypes = {
    */
   closeSidebar: propTypes.func.isRequired,
 
-  /** Callback for the "Create page note" button. */
+  /**
+   * Callback for the "Create annotation" / "Create page note" button. The type
+   * of annotation depends on whether there is a text selection and is decided
+   * by the caller.
+   */
   createAnnotation: propTypes.func.isRequired,
 
   /** Is the sidebar currently visible? */

src/annotator/sidebar.coffee

@@ -39,6 +39,7 @@ module.exports = class Sidebar extends Host
     if @plugins.BucketBar?
       @plugins.BucketBar.element.on 'click', (event) => this.show()
 
+    # Set up the toolbar on the left edge of the sidebar.
     toolbarContainer = document.createElement('div')
     @toolbar = new ToolbarController(toolbarContainer, {
       createAnnotation: => this.createAnnotation()

src/annotator/test/sidebar-test.coffee

@@ -365,7 +365,7 @@ describe 'Sidebar', ->
       sidebar.show()
       assert.isFalse sidebar.visibleHighlights
 
-    it 'updates the toolbar', ->
+    it 'updates the `sidebarOpen` property of the toolbar', ->
       sidebar = createSidebar()
       sidebar.show()
       assert.equal(fakeToolbar.sidebarOpen, true)
@@ -381,7 +381,7 @@ describe 'Sidebar', ->
 
       assert.isFalse sidebar.visibleHighlights
 
-    it 'updates the toolbar', ->
+    it 'updates the `sidebarOpen` property of the toolbar', ->
       sidebar = createSidebar()
 
       sidebar.show()

src/annotator/test/toolbar-test.js

@@ -88,7 +88,7 @@ describe('ToolbarController', () => {
     });
   });
 
-  it('toggles sidebar visibility', () => {
+  it('calls `setSidebarOpen` callback when sidebar toggle button is clicked', () => {
     const setSidebarOpen = sinon.stub();
     const controller = createToolbar({ setSidebarOpen });
 
@@ -100,7 +100,7 @@ describe('ToolbarController', () => {
     assert.calledWith(setSidebarOpen, false);
   });
 
-  it('closes the sidebar', () => {
+  it('calls `setSidebarOpen` callback when sidebar close button is clicked', () => {
     const setSidebarOpen = sinon.stub();
     const controller = createToolbar({ setSidebarOpen });
     controller.useMinimalControls = true;
@@ -110,7 +110,7 @@ describe('ToolbarController', () => {
     assert.calledWith(setSidebarOpen, false);
   });
 
-  it('toggles highlight visibility', () => {
+  it('calls `setHighlightsVisible` callback when highlights toggle button is clicked', () => {
     const setHighlightsVisible = sinon.stub();
     const controller = createToolbar({ setHighlightsVisible });
 
@@ -122,7 +122,7 @@ describe('ToolbarController', () => {
     assert.calledWith(setHighlightsVisible, false);
   });
 
-  it('creates an annotation', () => {
+  it('calls `createAnnotation` callback when Create Note/Annotation button is clicked', () => {
     const createAnnotation = sinon.stub();
     const setSidebarOpen = sinon.stub();
     createToolbar({ createAnnotation, setSidebarOpen });