default.commands: add documentation

1 files changed, 41 insertions, 0 deletions

diff --git a/ranger/defaults/commands.py b/ranger/defaults/commands.py
index bf8830c7..ac18faae 100644
--- a/ranger/defaults/commands.py
+++ b/ranger/defaults/commands.py
@@ -13,6 +13,47 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+'''
+This is the default file for command definitions.
+
+Each command is a subclass of `Command'.  Several methods are defined
+to interface with the console:
+	execute: call this method when the command is executed.
+	tab: call this method when tab is pressed.
+	quick: call this method after each keypress in the QuickCommandConsole.
+
+The return values for tab() can be either:
+	None: There is no tab completion
+	A string: Change the console to this string
+	A list/tuple/generator: cycle through every item in it
+The return value for quick() can be:
+	False: Nothing happens
+	True: Execute the command afterwards
+The return value for execute() doesn't matter.
+
+If you want to add custom commands, you can create a file
+~/.ranger/commands.py, add the line:
+	from ranger.api.commands import *
+
+and write some command definitions, for example:
+
+	class tabnew(Command):
+		def execute(self):
+			self.fm.tab_new()
+
+	class tabgo(Command):
+		"""
+		:tabgo <n>
+
+		Go to the nth tab.
+		"""
+		def execute(self):
+			num = self.line.split()[1]
+			self.fm.tab_open(int(num))
+		
+For a list of all actions, check /ranger/core/actions.py.
+'''
+
 from ranger.api.commands import *
 
 alias('e', 'edit')