Improve several test descriptions

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

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

@@ -24,18 +24,20 @@ describe('Toolbar', () => {
   const findButton = (wrapper, label) =>
     wrapper.find(`button[title="${label}"]`);
 
-  it('renders nothing if `useMinimalControls` is true and the sidebar is closed', () => {
-    const wrapper = createToolbar({ useMinimalControls: true });
-    assert.isFalse(wrapper.find('button').exists());
-  });
+  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', () => {
-    const wrapper = createToolbar({
-      useMinimalControls: true,
-      isSidebarOpen: true,
+    it('renders only the "Close" button if the sidebar is open', () => {
+      const wrapper = createToolbar({
+        useMinimalControls: true,
+        isSidebarOpen: true,
+      });
+      assert.equal(wrapper.find('button').length, 1);
+      assert.isTrue(findButton(wrapper, 'Close annotation sidebar').exists());
     });
-    assert.equal(wrapper.find('button').length, 1);
-    assert.isTrue(findButton(wrapper, 'Close annotation sidebar').exists());
   });
 
   it('renders the normal controls if `useMinimalControls` is 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

@@ -281,7 +281,7 @@ describe 'Sidebar', ->
       )
       show = sandbox.stub(sidebar, 'show')
       sidebar.publish('panelReady')
-      assert.calledOnce(show)        
+      assert.calledOnce(show)
 
     it 'opens the sidebar when a direct-linked group is present.', ->
       sidebar = createSidebar(
@@ -291,7 +291,7 @@ describe 'Sidebar', ->
       )
       show = sandbox.stub(sidebar, 'show')
       sidebar.publish('panelReady')
-      assert.calledOnce(show)        
+      assert.calledOnce(show)
 
     it 'opens the sidebar when a direct-linked query is present.', ->
       sidebar = createSidebar(
@@ -301,7 +301,7 @@ describe 'Sidebar', ->
       )
       show = sandbox.stub(sidebar, 'show')
       sidebar.publish('panelReady')
-      assert.calledOnce(show)        
+      assert.calledOnce(show)
 
     it 'opens the sidebar when openSidebar is set to true.', ->
       sidebar = createSidebar(
@@ -311,7 +311,7 @@ describe 'Sidebar', ->
       )
       show = sandbox.stub(sidebar, 'show')
       sidebar.publish('panelReady')
-      assert.calledOnce(show)        
+      assert.calledOnce(show)
 
     it 'does not show the sidebar if not configured to.', ->
       sidebar = createSidebar(
@@ -320,7 +320,7 @@ describe 'Sidebar', ->
       )
       show = sandbox.stub(sidebar, 'show')
       sidebar.publish('panelReady')
-      assert.notCalled(show)        
+      assert.notCalled(show)
 
 
 
@@ -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 });