Restructure how options are ordered. (de5b09e1) · Commits · extjs / jsduck

lib/jsduck/option_parser.rb

+1 −1

Original line number	Diff line number	Diff line
		@@ -87,7 +87,7 @@ module JsDuck

		# Returns long help text for a single option.
		def help_single(option_name)
		o = @full_options_index[option_name] \|\| {:keys => [option_name], :desc => ["No such option."]}
		o = @full_options_index[option_name] \|\| {:keys => [option_name], :desc => ["No such option. See --help=help"]}

		r = []

lib/jsduck/options.rb

+174 −162

Original line number	Diff line number	Diff line
		@@ -165,46 +165,15 @@ module JsDuck
		@output_dir = path == "-" ? :stdout : canonical(path)
		end

		opts.on('--ignore-global',
		"Turns off the creation of 'global' class.",
		"",
		"The 'global' class gets created when members that",
		"don't belong to any class are found - all these",
		"members will be placed into the 'global' class.",
		"",
		"Using this option won't suppress the warning that's",
		"given when global members are found. For that you",
		"need to additionally use --warnings=-global") do
		@ignore_global = true
		end

		opts.on('--external=Foo,Bar,Baz', Array,
		"Declares list of external classes.",
		"",
		"These classes will then no more generate warnings",
		"when used in type definitions or inherited from.",
		"",
		"Multiple classes can be given in comma-separated list,",
		"or by using the option repeatedly.") do \|classes\|
		@external_classes += classes
		end

		opts.on('--[no-]ext4-events',
		"Forces appending of Ext4-style options param to events.",
		"",
		"In Ext JS 4 and Sencha Touch 2 all event handlers are",
		"passed an additional options object at the end of the",
		"parameters list. This options object is skipped in the",
		"documentation of Ext4/Touch2 events, so it needs to be",
		"appended by JSDuck.",
		opts.on('--export=TYPE',
		"Exports docs in JSON.",
		"",
		"The default is to auto-detect if we're using Ext JS 4",
		"or Sencha Touch 2 based on whether the code defines",
		"classes using Ext.define(), and only then append the",
		"options parameter. This should work most of the time.",
		"TYPE is one of:",
		"",
		"Use this option to override the auto-detection.") do \|e\|
		@ext4_events = e
		"- full - full class docs.",
		"- api - only class- and member names.",
		"- examples - extracts inline examples from classes.") do \|format\|
		@export = format.to_sym
		end

		opts.on('--builtin-classes',
		@@ -223,26 +192,38 @@ module JsDuck
		read_filenames(@root_dir + "/js-classes")
		end

		opts.on('--meta-tags=PATH',
		"Path to custom meta-tag implementations.",
		opts.on('--seo', "Enables SEO-friendly print version.",
		"",
		"Can be a path to single Ruby file or a directory.",
		"Instead of index.html creates index.php that will serve",
		"the regular docs, print-friendly docs, and search-engine-",
		"friendly docs (the latter two are pretty much the same).") do
		@seo = true
		end

		opts.on('--config=PATH',
		"Loads config options from JSON file.",
		"",
		"This option can be used repeatedly to include multiple",
		"meta tags from different places.",
		"An alternative to listing all options on command line.",
		"",
		"See also: https://github.com/senchalabs/jsduck/wiki/Custom-tags") do \|path\|
		@meta_tag_paths << canonical(path)
		"See also: https://github.com/senchalabs/jsduck/wiki/Config-file") do \|path\|
		path = canonical(path)
		if File.exists?(path)
		config = read_json_config(path)
		else
		Logger.instance.fatal("The config file #{path} doesn't exist")
		exit(1)
		end
		# treat paths inside JSON config relative to the location of
		# config file. When done, switch back to current working dir.
		@working_dir = File.dirname(path)
		optparser.parse!(config).each {\|fname\| read_filenames(canonical(fname)) }
		@working_dir = nil
		end

		opts.on('--encoding=NAME', "Input encoding (defaults to UTF-8).") do \|encoding\|
		JsDuck::IO.encoding = encoding
		end

		opts.on('-v', '--verbose', "This will fill up your console.") do
		Logger.instance.verbose = true
		end

		opts.separator ""
		opts.separator "Customizing output:"
		opts.separator ""
		@@ -349,6 +330,117 @@ module JsDuck
		@images << canonical(path)
		end

		opts.on('--tests',
		"Creates page for testing inline examples.") do
		@tests = true
		end

		opts.on('--stats',
		"Creates page with all kinds of statistics.") do
		@stats = true
		end

		opts.on('--import=VERSION:PATH',
		"Imports exported docs generating @since & @new tags.",
		"",
		"For example:",
		"",
		" --import='1.0:/path/to/first/version'",
		" --import='2.0:/path/to/second/version'",
		" --import='3.0",
		"",
		"Several versions can be imported using the option multiple",
		"times. The last version must always be the current one",
		"without the :PATH portion.",
		"",
		"JSDuck will then check in which version every class/member",
		"first appears in and tag it with an appropriate @since tag.",
		"Things appearing only in the latest version will also get",
		"a @new tag (unless --new-since option is used).",
		"",
		"See also: https://github.com/senchalabs/jsduck/wiki/@since") do \|v\|
		if v =~ /\A(.?):(.)\Z/
		@imports << {:version => $1, :path => canonical($2)}
		else
		@imports << {:version => v}
		end
		end

		opts.on('--new-since=VERSION',
		"Since which version to label items with @new tag.",
		"",
		"The VERSION must be one of the version names defined",
		"with --import option.",
		"",
		"Defaults to the last version listed by --import.") do \|v\|
		@new_since = v
		end

		opts.separator ""
		opts.separator "Tweaking:"
		opts.separator ""

		opts.on('--meta-tags=PATH',
		"Path to custom meta-tag implementations.",
		"",
		"Can be a path to single Ruby file or a directory.",
		"",
		"This option can be used repeatedly to include multiple",
		"meta tags from different places.",
		"",
		"See also: https://github.com/senchalabs/jsduck/wiki/Custom-tags") do \|path\|
		@meta_tag_paths << canonical(path)
		end

		opts.on('--ignore-global',
		"Turns off the creation of 'global' class.",
		"",
		"The 'global' class gets created when members that",
		"don't belong to any class are found - all these",
		"members will be placed into the 'global' class.",
		"",
		"Using this option won't suppress the warning that's",
		"given when global members are found. For that you",
		"need to additionally use --warnings=-global") do
		@ignore_global = true
		end

		opts.on('--external=Foo,Bar,Baz', Array,
		"Declares list of external classes.",
		"",
		"These classes will then no more generate warnings",
		"when used in type definitions or inherited from.",
		"",
		"Multiple classes can be given in comma-separated list,",
		"or by using the option repeatedly.") do \|classes\|
		@external_classes += classes
		end

		opts.on('--[no-]ext4-events',
		"Forces appending of Ext4 options param to events.",
		"",
		"In Ext JS 4 and Sencha Touch 2 all event handlers are",
		"passed an additional options object at the end of the",
		"parameters list. This options object is skipped in the",
		"documentation of Ext4/Touch2 events, so it needs to be",
		"appended by JSDuck.",
		"",
		"The default is to auto-detect if we're using Ext JS 4",
		"or Sencha Touch 2 based on whether the code defines",
		"classes using Ext.define(), and only then append the",
		"options parameter. This should work most of the time.",
		"",
		"Use this option to override the auto-detection.") do \|e\|
		@ext4_events = e
		end

		opts.on('--examples-base-url=URL',
		"Base URL for examples with relative URL-s.",
		" ",
		"Defaults to: 'extjs-build/examples/'") do \|path\|
		@examples_base_url = path
		end

		opts.on('--link=TPL',
		"HTML template for replacing {@link}.",
		"",
		@@ -377,25 +469,6 @@ module JsDuck
		@img_tpl = tpl
		end

		opts.on('--export=TYPE',
		"Exports docs in JSON.",
		"",
		"TYPE is one of:",
		"",
		"- full - full class docs.",
		"- api - only class- and member names.",
		"- examples - extracts inline examples from classes.") do \|format\|
		@export = format.to_sym
		end

		opts.on('--seo', "Enables SEO-friendly print version.",
		"",
		"Instead of index.html creates index.php that will serve",
		"the regular docs, print-friendly docs, and search-engine-",
		"friendly docs (the latter two are pretty much the same).") do
		@seo = true
		end

		opts.on('--eg-iframe=PATH',
		"An HTML file used to display inline examples.",
		"",
		@@ -408,30 +481,37 @@ module JsDuck
		@eg_iframe = canonical(path)
		end

		opts.on('--examples-base-url=URL',
		"Base URL for examples with relative URL-s.",
		opts.on('--ext-namespaces=Ext,Foo', Array,
		"Additional ExtJS/Touch namespaces to recognize.",
		"",
		"Defaults to: 'extjs-build/examples/'") do \|path\|
		@examples_base_url = path
		end

		opts.on('--tests',
		"Creates page for testing inline examples.") do
		@tests = true
		"Defaults to 'Ext'",
		"",
		"Useful when using Ext JS in sandbox mode where instead",
		"of Ext.define() your code contains YourNs.define().",
		"In such case pass --ext-namespaces=Ext,YourNS option",
		"and JSDuck will recognize both Ext.define() and",
		"YourNs.define() plus few other things that depend on",
		"Ext namespace like Ext.emptyFn.") do \|ns\|
		@ext_namespaces = ns
		end

		opts.on('--stats',
		"Creates page with all kinds of statistics.") do
		@stats = true
		opts.on('--touch-examples-ui',
		"Turns on phone/tablet UI for examples.",
		"",
		"This is a very Sencha Touch 2 docs specific option.",
		"Effects both normal- and inline-examples.") do
		@touch_examples_ui = true
		end

		opts.separator ""
		opts.separator "Debugging:"
		opts.separator ""

		opts.on('--pretty-json',
		"Turns on pretty-printing of JSON.") do
		@pretty_json = true
		opts.on('-v', '--verbose',
		"Turns on excessive logging.",
		"",
		"Log messages are writted to STDERR.") do
		Logger.instance.verbose = true
		end

		opts.on('--warnings=+A,-B,+C', Array,
		@@ -465,6 +545,16 @@ module JsDuck
		@processes = count.to_i
		end

		opts.on('--pretty-json',
		"Turns on pretty-printing of JSON.",
		"",
		"This is useful when studying the JSON files generated",
		"by --export option. But the option effects any JSON",
		"that gets generated, so it's also useful when debugging",
		"the resource files generated for the docs app.") do
		@pretty_json = true
		end

		opts.on('--template=PATH',
		"Directory containing the UI template files.",
		"",
		@@ -498,84 +588,6 @@ module JsDuck
		@local_storage_db = name
		end

		opts.on('--touch-examples-ui',
		"Turns on phone/tablet UI for examples.",
		"",
		"This is a very Sencha Touch 2 docs specific option.",
		"Effects both normal- and inline-examples.") do
		@touch_examples_ui = true
		end

		opts.on('--ext-namespaces=Ext,Foo', Array,
		"Additional ExtJS/Touch namespaces to recognize.",
		"",
		"Defaults to 'Ext'",
		"",
		"Useful when using Ext JS in sandbox mode where instead",
		"of Ext.define() your code contains YourNs.define().",
		"In such case pass --ext-namespaces=Ext,YourNS option",
		"and JSDuck will recognize both Ext.define() and",
		"YourNs.define() plus few other things that depend on",
		"Ext namespace like Ext.emptyFn.") do \|ns\|
		@ext_namespaces = ns
		end

		opts.on('--import=VERSION:PATH',
		"Imports exported docs generating @since & @new tags.",
		"",
		"For example:",
		"",
		" --import='1.0:/path/to/first/version'",
		" --import='2.0:/path/to/second/version'",
		" --import='3.0",
		"",
		"Several versions can be imported using the option multiple",
		"times. The last version must always be the current one",
		"without the :PATH portion.",
		"",
		"JSDuck will then check in which version every class/member",
		"first appears in and tag it with an appropriate @since tag.",
		"Things appearing only in the latest version will also get",
		"a @new tag (unless --new-since option is used).",
		"",
		"See also: https://github.com/senchalabs/jsduck/wiki/@since") do \|v\|
		if v =~ /\A(.?):(.)\Z/
		@imports << {:version => $1, :path => canonical($2)}
		else
		@imports << {:version => v}
		end
		end

		opts.on('--new-since=VERSION',
		"Since which version to label items with @new tag.",
		"",
		"The VERSION must be one of the version names defined",
		"with --import option.",
		"",
		"Defaults to the last version listed by --import.") do \|v\|
		@new_since = v
		end

		opts.on('--config=PATH',
		"Loads config options from JSON file.",
		"",
		"An alternative to listing all options on command line.",
		"",
		"See also: https://github.com/senchalabs/jsduck/wiki/Config-file") do \|path\|
		path = canonical(path)
		if File.exists?(path)
		config = read_json_config(path)
		else
		Logger.instance.fatal("The config file #{path} doesn't exist")
		exit(1)
		end
		# treat paths inside JSON config relative to the location of
		# config file. When done, switch back to current working dir.
		@working_dir = File.dirname(path)
		optparser.parse!(config).each {\|fname\| read_filenames(canonical(fname)) }
		@working_dir = nil
		end

		opts.on('-h', '--help[=--some-option]',
		"This help or --help=--option for help on specific option.",
		"",