[PATCH 07/25] Write better sub commands comments.

[doron.behar@xxxxxxxxx]

From: Doron Behar <doron.behar@xxxxxxxxx>

---
 Completion/Unix/Command/_luarocks | 87 ++++++++++++++++++++++++-------
 1 file changed, 67 insertions(+), 20 deletions(-)

diff --git a/Completion/Unix/Command/_luarocks b/Completion/Unix/Command/_luarocks
index 990582d99..b9f6c8af6 100644
--- a/Completion/Unix/Command/_luarocks
+++ b/Completion/Unix/Command/_luarocks
@@ -1,6 +1,9 @@
 #compdef luarocks
 
-# {{{ `build` command receives as an argument a .rockspec file, or external rock and afterwards a version
+# {{{ `build` command
+# arguments:
+# - must: .rockspec file / external rock
+# - optional: version (only when chossing external rock)
 local make_command_options=(
 	'--pack-binary-rock[Produce a .rock file with the contents of compilation inside the current directory instead of installing it]'
 	'--keep[Do not remove previously installed versions of the rock after building a new one]'
@@ -24,7 +27,9 @@ __luarocks_deps_mode(){
 _luarocks_build(){
 }
 # }}}
-# {{{ `config` command sets a flag in the format VAR=VALUE
+# {{{ `config` command
+# arguments:
+# - must: VAR=VALUE
 local config_command_options=(
 	'--lua-incdir[Path to Lua header files]'
 	'--lua-libdir[Path to Lua library files]'
@@ -36,7 +41,9 @@ local config_command_options=(
 _luarocks_config(){
 }
 # }}}
-# {{{ `doc` command ... TODO: what kind of argument it receives
+# {{{ `doc` command
+# arguments:
+# - TODO
 local doc_command_options=(
 	'--home[Open the home page of project]'
 	'--list[List documentation files only]'
@@ -44,7 +51,9 @@ local doc_command_options=(
 _luarocks_doc(){
 }
 # }}}
-# {{{ `download` command receives an argument of an external only rockspec
+# {{{ `download` command
+# arguments:
+# - must: external only rockspec
 local download_command_options=(
 	'--all[Download all files if there are multiple matches]'
 	'--source[Download .src.rock if available]'
@@ -54,19 +63,28 @@ local download_command_options=(
 _luarocks_download(){
 }
 # }}}
-# {{{ `help` command receives an argument of an internal command
+# {{{ `help` command
+# arguments:
+# must: luarocks sub command
 _luarocks_help(){
 }
 # }}}
-# {{{ `install` command receives the same argument as the build command and it accepts the same options as well
+# {{{ `install` command
+# arguments:
+# - must: .rockspec file, or external rock
+# - optional: version
+# NOTE: it receives the same argument as the build command and it accepts the same options as well
 _luarocks_install(){
 }
 # }}}
-# {{{ `lint` command receives an argument of a rockspec file
+# {{{ `lint` command
+# arguments:
+# must: rockspec file (first and last)
 _luarocks_lint(){
 }
 # }}}
-# {{{ `list` command receives only options
+# {{{ `list` command
+# NOTE: receives only options
 local list_command_options=(
 	'--outdated[List only rocks for which there is a higher version available in the rocks server]'
 	'--porcelain[Produce machine-friendly output]'
@@ -74,23 +92,33 @@ local list_command_options=(
 _luarocks_list(){
 }
 # }}}
-# {{{ `make` command receives an argument of a rockspec file
-# it's options were already described above.
+# {{{ `make` command
+# arguments:
+# - optional: rockspec file
+# NOTE: it's options were already described above.
 _luarocks_make(){
 }
 # }}}
-# {{{ `new_version` command receives an argument a .rockspec file, or external rock and afterwards a version and optionally afterwards a URL
+# {{{ `new_version` command
+# arguments:
+# - optional: .rockspec file / external rock
+# - optional: version (unless a --tag was given)
+# - optional: URL
 local new_version_command_options=(
 	'--tag=[if no version is specified, this option'"'"'s argument is used instead]:TAG:__git_tag'
 )
 _luarocks_new_version(){
 }
 # }}}
-# {{{ `pack` command receives as an argument a .rockspec file, or external rock and afterwards a version
+# {{{ `pack` command
+# arguments:
+# - must: .rockspec file / external rock
+# - optional: version
 _luarocks_pack(){
 }
 # }}}
-# {{{ `path` command receives only options
+# {{{ `path` command
+# NOTE: receives only options
 local path_command_options=(
 	'--bin[Adds the system path to the output]'
 	'--append[Appends the paths to the existing paths]'
@@ -101,7 +129,9 @@ local path_command_options=(
 _luarocks_path(){
 }
 # }}}
-# {{{ `purge` command receives only options, --tree is mandatory, --force can be used only in conjunction with --old-versions
+# {{{ `purge` command
+# NOTE: receives only options yet --tree is mandatory
+# NOTE: --force can be used only in conjunction with --old-versions
 local option_force='--force[Force removing old versions when]'
 local purge_command_options=(
 	'--old-versions[Keep the highest-numbered version of each rock and remove the other ones]'
@@ -110,7 +140,10 @@ local purge_command_options=(
 _luarocks_purge(){
 }
 # }}}
-# {{{ `remove` command receives as an argument a name of a locally installed rock
+# {{{ `remove` command
+# arguments:
+# - must: locally installed rock
+# - optional: version
 local option_force_fast='--force-fast[works like --force but doesn'"'"'t reports forced removals]'
 local remove_command_options=(
 	$option_deps_mode
@@ -120,7 +153,9 @@ local remove_command_options=(
 _luarocks_remove(){
 }
 # }}}
-# {{{ `search` command receives as an argument only a string as a search query
+# {{{ `search` command
+# arguments:
+# - must: string as a search query
 local search_command_options=(
 	'--source[Return only rockspecs and source rocks]'
 	'--binary[Return only pure Lua and binary rocks (rocks that can be used with the "install" command without requiring a C toolchain)]'
@@ -129,7 +164,9 @@ local search_command_options=(
 _luarocks_search(){
 }
 # }}}
-# {{{ `show` command receives as an argument only an installed rock
+# {{{ `show` command
+# arguments:
+# - must: installed rock
 local show_command_options=(
 	'--home[home page of project]'
 	'--modules[all modules provided by this package as used by require()]'
@@ -142,14 +179,19 @@ local show_command_options=(
 _luarocks_show(){
 }
 # }}}
-# {{{ `unpack` command receives as an argument a rock package or an external rock and afterwards a version
+# {{{ `unpack` command
+# arguments:
+# - must: rock package file / an external rock 
+# - optional: version (only when chossing external rock)
 local unpack_command_options=(
 	'--force[Unpack files even if the output directory already exists]'
 )
 _luarocks_unpack(){
 }
 # }}}
-# {{{ `upload` command receives as an argument a rockspec file with .src.rock extension
+# {{{ `upload` command
+# arguments:
+# - must: rockspec file with .src.rock extension
 local upload_command_options=(
 	'--skip-pack[Do not pack and send source rock]'
 	'--api-key=[Give it an API key]:KEY:{_message "api key"}'
@@ -158,7 +200,12 @@ local upload_command_options=(
 _luarocks_upload(){
 }
 # }}}
-# {{{ `write_rockspec` command receives as an argument a name and a version with optionally a URL/PATH
+# {{{ `write_rockspec` command
+# arguments:
+# - optional: name
+# - optional: version
+# - optional: URL / PATH
+# receives as an argument a name and a version with optionally a URL/PATH
 local write_rockspec_command_options=(
 	'--output=[Write the rockspec with the given filename]:FILE:_files'
 	'--license=[A license string, ]:LICENSE:{_message -e "write a license string such as "MIT/X11" or "GNU GPL v3"}'
-- 
2.17.0