From 3d46888b288f4a8bf348b84e82ef632a449b9d87 Mon Sep 17 00:00:00 2001 From: Andy Meneely Date: Sat, 5 Nov 2016 00:23:17 -0400 Subject: [PATCH] docs: cleanup of parameters page [skip ci] --- docs/parameters.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/parameters.rst b/docs/parameters.rst index 9cc62a3..808094e 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -3,11 +3,15 @@ Parameters are Optional Squib is all about sane defaults and shorthand specification. Arguments to DSL methods are almost always using hashes, which look a lot like `Ruby 2.0's named parameters `_. This means you can specify your parameters in any order you please. All parameters are optional. -For example `x` and `y` default to 0 (i.e. the upper-left corner of the card). Any parameter that is specified in the command overrides any Squib defaults, `config.yml` settings, or layout rules. +For example ``x`` and ``y`` default to ``0`` (i.e. the upper-left corner of the card). Any parameter that is specified in the command overrides any Squib defaults or layout rules. -.. highlight:: none +You must use *named parameters* rather than *positional parameters*. For example:: -Note: you MUST use named parameters rather than positional parameters. For example: ``save :png`` will lead to an error like this:: + save(:png) # wrong + +will lead to an error like this: + +.. code-block:: none C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.3/lib/squib/api/save.rb:12:in `save': wrong number of arguments (2 for 0..1) (ArgumentError) from deck.rb:22:in `block in
' @@ -16,11 +20,15 @@ Note: you MUST use named parameters rather than positional parameters. For examp from deck.rb:18:in `new' from deck.rb:18:in `
' -Instead, you must name the parameters: `save format: :png` +Instead, you must name the parameters:: + + save(format: :png) # the right way .. warning:: If you provide an option to a DSL method that the DSL method does not recognize, Squib ignores the extraenous option without warning. For example, these two calls have identical behavior:: save_png prefix: 'front_' - save_png prefix: 'front_', narf: true + save_png prefix: 'front_', narf: true # narf has no effect + + This can be troublesome when you accidentally misspell an option and don't realize it.