From 1c39b851e41be3a95e433189f43ec5fe9faaa11f Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Fri, 23 Aug 2013 12:14:48 -0700 Subject: [PATCH] Update AtomApplication to new documentation style --- src/atom-application.coffee | 96 ++++++++++++------------------------- 1 file changed, 31 insertions(+), 65 deletions(-) diff --git a/src/atom-application.coffee b/src/atom-application.coffee index eda003e4d..0b6895e48 100644 --- a/src/atom-application.coffee +++ b/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/ 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})