docs: def updateResults( self ):
          """Update our results within any pending results that have completed since we
          last retrieved results from the cluster.
  
          :returns: the number of pending results completed at this call"""
  
          # we do all the tests for pending results against the notebook directly,
          # as the corresponding methods on self call this method themselves
          nb = self.notebook()
  
          # look for pending results if we're waiting for any
          n = 0
          if nb.numberOfPendingResults() > 0:
              # we have results to get
              self.open()
              for j in set(nb.pendingResults()):
                  # query the status of a job
                  status = self._client.result_status(j, status_only = False)
                      
                  # add all completed jobs to the notebook
                  if j in status['completed']:
                      r = status[j]
                          
                      # update the result in the notebook, cancelling
                      # the pending result as well
                      # values come back from Client.result_status() in
                      # varying degrees of list-nesting, which LabNotebook.addResult()
                      # handles itself
                      nb.addResult(r, j)
  
                      # commit changes to the notebook
                      nb.commit()
  
                      # purge the completed job from the cluster
                      self._client.purge_hub_results(j)
                           
                      # record that we retrieved the results for the given job
                      n = n + 1
          return n