Update AtomApplication to new documentation style

src/atom-application.coffee

@@ -25,8 +25,6 @@ class AtomApplication
   _.extend @prototype, EventEmitter.prototype
 
   # Public: The entry point into the Atom application.
-  #
-  # Returns nothing.
   @open: (options) ->
     createAtomApplication = -> new AtomApplication(options)
 
@@ -73,20 +71,12 @@ class AtomApplication
     else
       @openPath({pidToKillWhenClosed, newWindow, devMode}) # Always open a editor window if this is the first instance of Atom.
 
-  # Public: Removes a window from the global window list.
-  #
-  # window - The relevant {AtomWindow}
-  #
-  # Returns nothing.
+  # Public: Removes the {AtomWindow} from the global window list.
   removeWindow: (window) ->
     @windows.splice @windows.indexOf(window), 1
     @applicationMenu?.enableWindowSpecificItems(false) if @windows.length == 0
 
-  # Public: Adds a window to the global window list.
-  #
-  # window - The relevant {AtomWindow}
-  #
-  # Returns nothing.
+  # Public: Adds the {AtomWindow} to the global window list.
   addWindow: (window) ->
     @windows.push window
     @applicationMenu?.enableWindowSpecificItems(true)
@@ -96,8 +86,6 @@ class AtomApplication
   # You can run the atom command multiple times, but after the first launch
   # the other launches will just pass their information to this server and then
   # close immediately.
-  #
-  # Returns nothing.
   listenForArgumentsFromNewProcess: ->
     fs.unlinkSync socketPath if fs.existsSync(socketPath)
     server = net.createServer (connection) =>
@@ -109,16 +97,10 @@ class AtomApplication
     server.on 'error', (error) -> console.error 'Application server failed', error
 
   # Private: Configures required javascript environment flags.
-  #
-  # Returns nothing.
   setupJavaScriptArguments: ->
     app.commandLine.appendSwitch 'js-flags', '--harmony_collections'
 
-  # Private: Determines whether the auto updater should check for updates.
-  #
-  # If running from a local build, we don't want to update to a released version.
-  #
-  # Returns nothing.
+  # Private: Enable updates unless running from a local build of Atom.
   checkForUpdates: ->
     versionIsSha = /\w{7}/.test @version
 
@@ -130,11 +112,7 @@ class AtomApplication
       autoUpdater.setAutomaticallyChecksForUpdates true
       autoUpdater.checkForUpdatesInBackground()
 
-  # Private: Registers basic application commands.
-  #
-  # This should only be called once.
-  #
-  # Returns nothing.
+  # Private: Registers basic application commands, non-idempotent.
   handleEvents: ->
     @on 'application:about', -> Menu.sendActionToFirstResponder('orderFrontStandardAboutPanel:')
     @on 'application:run-all-specs', -> @runSpecs(exitWhenDone: false, resourcePath: global.devResourcePath)
@@ -188,53 +166,42 @@ class AtomApplication
   #
   # If it isn't handled globally, delegate to the currently focused window.
   #
-  # command - The string representing the command.
-  # args    - The optional arguments to pass along.
+  # _Arguments_
   #
-  # Returns nothing.
+  # * command - The string representing the command.
+  # * args - The optional arguments to pass along.
   sendCommand: (command, args...) ->
     unless @emit(command, args...)
       @focusedWindow()?.sendCommand(command, args...)
 
-  # Private: Selects the window based on the given path.
-  #
-  # pathToOpen - The full file path used to select the window.
-  #
-  # FIXME: This should probably return undefined if no window is found.
-  #
-  # Returns the {AtomWindow} which is opened to the selected path and the list
-  #   of windows otherwise.
+  # Private: Returns the {AtomWindow} for the given path.
   windowForPath: (pathToOpen) ->
     for atomWindow in @windows
       return atomWindow if atomWindow.containsPath(pathToOpen)
 
-  # Public: Finds the currently focused window.
-  #
-  # Returns the currently focused {AtomWindow} or undefined if none are focused.
+  # Public: Returns the currently focused {AtomWindow} or undefined if none.
   focusedWindow: ->
     _.find @windows, (atomWindow) -> atomWindow.isFocused()
 
   # Public: Opens multiple paths, in existing windows if possible.
   #
-  # options -
-  #   pathsToOpen: The array of file paths to open
-  #   pidToKillWhenClosed: The integer of the pid to kill
-  #   newWindow: Boolean of whether this should be opened in a new window.
-  #   devMode: Boolean to control the opened window's dev mode.
+  # _Options_
   #
-  # Returns nothing.
+  # + pathsToOpen - The array of file paths to open
+  # + pidToKillWhenClosed - The integer of the pid to kill
+  # + newWindow - Boolean of whether this should be opened in a new window.
+  # + devMode - Boolean to control the opened window's dev mode.
   openPaths: ({pathsToOpen, pidToKillWhenClosed, newWindow, devMode}) ->
     @openPath({pathToOpen, pidToKillWhenClosed, newWindow, devMode}) for pathToOpen in pathsToOpen ? []
 
   # Public: Opens a single path, in an existing window if possible.
   #
-  # options -
-  #   pathsToOpen: The array of file paths to open
-  #   pidToKillWhenClosed: The integer of the pid to kill
-  #   newWindow: Boolean of whether this should be opened in a new window.
-  #   devMode: Boolean to control the opened window's dev mode.
+  # _Options_
   #
-  # Returns nothing.
+  # + pathsToOpen - The array of file paths to open
+  # + pidToKillWhenClosed - The integer of the pid to kill
+  # + newWindow - Boolean of whether this should be opened in a new window.
+  # + devMode - Boolean to control the opened window's dev mode.
   openPath: ({pathToOpen, pidToKillWhenClosed, newWindow, devMode}={}) ->
     unless devMode
       existingWindow = @windowForPath(pathToOpen) unless pidToKillWhenClosed or newWindow
@@ -265,9 +232,10 @@ class AtomApplication
   #
   # Currently only supports atom://session/<session-id> urls.
   #
-  # options -
-  #   urlToOpen: The atom:// url to open.
-  #   devMode: Boolean to control the opened window's dev mode.
+  # _Options_
+  #
+  # + urlToOpen - The atom:// url to open.
+  # + devMode - Boolean to control the opened window's dev mode.
   openUrl: ({urlToOpen, devMode}) ->
     parsedUrl = url.parse(urlToOpen)
     if parsedUrl.host is 'session'
@@ -281,13 +249,12 @@ class AtomApplication
 
   # Private: Opens up a new {AtomWindow} to run specs within.
   #
-  # options -
-  #   exitWhenDone: A Boolean that if true, will close the window upon completion.
-  #   resourcePath: The path to include specs from.
-  #   specPath: The directory to load specs from.
+  # _Options_
   #
-  # Returns nothing.
-  runSpecs: ({exitWhenDone, resourcePath, specPath}) ->
+  # + exitWhenDone - A Boolean that if true, will close the window upon completion.
+  # + resourcePath - The path to include specs from.
+  # + specPath - The directory to load specs from.
+  runSpecs: ({exitWhenDone, resourcePath}) ->
     if resourcePath isnt @resourcePath and not fs.existsSync(resourcePath)
       resourcePath = @resourcePath
 
@@ -300,11 +267,10 @@ class AtomApplication
   #
   # Once paths are selected, they're opened in a new or existing {AtomWindow}s.
   #
-  # options -
-  #   devMode: A Boolean which controls whether any newly opened windows should
-  #            be in dev mode or not.
+  # _Options_
   #
-  # Returns nothing
+  # + devMode - A Boolean which controls whether any newly opened windows should
+  #   be in dev mode or not.
   promptForPath: ({devMode}={}) ->
     pathsToOpen = dialog.showOpenDialog title: 'Open', properties: ['openFile', 'openDirectory', 'multiSelections', 'createDirectory']
     @openPaths({pathsToOpen, devMode})