additions and normalization of documentation and comments

CHANGELOG.md

@@ -95,16 +95,16 @@
 
 ### Important Changes
 
-- Added an [initializer_example.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/initializer_example.rb) that you can use as an easy template for pagy configuration
-- Integrated extras from `pagy-extras` gem into pagy, now optionally required in the initializer
+- Added an [initializer_example.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/initializer_example.rb) that you can use as an easy template for Pagy configuration
+- Integrated extras from `pagy-extras` gem into Pagy, now optionally required in the initializer
 - Refactored I18n: simpler code and simpler configuration now based on the `I18n` extra
 - Reorganized documentation and added a few more how-to topics
 - Added the `:page_param` variable used to get the page number from and create the URL for the page links
 
 ### Breaking Changes
 
-- Extras are now integrated in pagy. The `pagy-extras` gem has been discontinued: you should remove it and update your code as indicated [here](https://github.com/ddnexus/pagy-extras)
-- Pagy I18n has been refactored and it's simpler to use. The main change is that the `Pagy::I18N[:gem]` variable has been removed, so if you want to use the `I18n` gem in place of the internal pagy implementation you need just to `require 'pagy/extra/i18n'` in your initializer. (see the [I18n doc](https://ddnexus.github.io/pagy/api/frontend.md#i18n))
+- Extras are now integrated in Pagy. The `pagy-extras` gem has been discontinued: you should remove it and update your code as indicated [here](https://github.com/ddnexus/pagy-extras)
+- Pagy I18n has been refactored and it's simpler to use. The main change is that the `Pagy::I18N[:gem]` variable has been removed, so if you want to use the `I18n` gem in place of the internal Pagy implementation you need just to `require 'pagy/extra/i18n'` in your initializer. (see the [I18n doc](https://ddnexus.github.io/pagy/api/frontend.md#i18n))
 - `pagy_url_for` now requires the pagy argument and it's called with 2 params: if you have overridden it, you should add the extra param.
 - `pagy_get_vars` now requires the vars argument and it's called with 2 params: if you have overridden it, you should add the extra param.
 - `pagy_array_get_vars` now requires the vars argument and it's called with 2 params: if you have overridden it, you should add the extra param.

README.md

@@ -34,7 +34,7 @@ _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#eff
 
 - Pagy is just ~100 lines of simple ruby, organized in 3 flat modules very easy to understand and use _(see [more...](https://ddnexus.github.io/pagy/api))_
 - No dependencies: it produces its own HTML, URLs, pluralization and interpolation with its own specialized and fast code _(see [why...](https://ddnexus.github.io/pagy/index#specialized-code-instead-of-generic-helpers))_
-- 100% of its methods are public API, accessible and overridable **right where you use them** (no need of monkey patching or subclassing)
+- 100% of its methods are public API, accessible and overridable **right where you use them** (no need of monkey-patching)
 
 ### Totally Agnostic
 

docs/api.md

@@ -5,7 +5,7 @@ title: API
 
 [![Gem Version](https://badge.fury.io/rb/pagy.svg)](https://badge.fury.io/rb/pagy)
 
-The whole core structure of pagy is very simple: it is organized around 3 small modules of just ~100 lines of code in total:
+The whole core structure of Pagy is very simple: it is organized around 3 small modules of just ~100 lines of code in total:
 
 | Module           | Description                                                                                                     | Links                                                                                                        |
 | --------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |

docs/api/backend.md

@@ -7,7 +7,7 @@ This module _(see [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/
 
 For overriding convenience, the `pagy` method calls two sub-methods that you may want to override in order to customize it for any type of collection (e.g. different ORM types, Array, elasticsearch results, etc.).
 
-However, keep in mind that the whole module is basically providing a single functionality: getting a pagy instance and the paginated items. You could re-write the whole module as one single and simple method specific to your need. (see [Writing your own pagy methods](#writing-your-own-pagy-methods))
+However, keep in mind that the whole module is basically providing a single functionality: getting a Pagy instance and the paginated items. You could re-write the whole module as one single and simple method specific to your need. (see [Writing your own Pagy methods](#writing-your-own-pagy-methods))
 
 **Notice**: This module is also extended with a few _specific_ extra methods that paginate array collections, if you use the [array extra](../extras/array.md).
 
@@ -32,7 +32,7 @@ end
 
 All the methods in this module are prefixed with the `"pagy_"` string, to avoid any possible conflict with your own methods when you include the module in your controller. They are also all private, so they will not be available as actions. The methods prefixed with the `"pagy_get_"` string are sub-methods/getter methods that are intended to be overridden, not used directly.
 
-Please, keep in mind that overriding any method is very easy with pagy. Indeed you can do it right where you are using it: no need of monkey-patching or subclassing or perform any tricky gymnic.
+Please, keep in mind that overriding any method is very easy with Pagy. Indeed you can do it right where you are using it: no need of monkey-patching or perform any tricky gymnic.
 
 ### pagy(collection, vars=nil)
 
@@ -44,26 +44,26 @@ This is the main method of this module. It takes a collection object (e.g. a sco
 
 The built-in `pagy` method is designed to be easy to customize by overriding any of the two sub-methods that it calls internally. You can independently change the default variables (`pagy_get_variables`) and/or the default page of items from the collection `pagy_get_items`).
 
-If you need to use multiple different types of collections in the same app or action, you may want to define some alternative and self contained custom `pagy` method. (see [Writing your own pagy methods](#writing-your-own-pagy-methods))
+If you need to use multiple different types of collections in the same app or action, you may want to define some alternative and self contained custom `pagy` method. (see [Writing your own Pagy methods](#writing-your-own-pagy-methods))
 
 ### pagy_get_vars(collection, vars)
 
-Sub-method called only by the `pagy` method, it returns the hash of variables used to initialize the pagy object.
+Sub-method called only by the `pagy` method, it returns the hash of variables used to initialize the Pagy object.
 
 Here is its source:
 
 ```ruby
 # sub-method called only by #pagy: here for easy customization of variables by overriding
 def pagy_get_vars(collection, vars)
-  # return the merged variables to initialize the pagy object
+  # return the merged variables to initialize the Pagy object
   { count: collection.count(:all),
     page:  params[vars[:page_param]||VARS[:page_param]] }.merge!(vars)
 end
 ```
 
 Override it if you need to add or change some variable. For example you may want to add the `:item_path` or the `:item_name` to customize the `pagy_info` output, or even cache the `count`.
 
-_IMPORTANT_: `:count` and `:page` are the only 2 required pagy core variables, so be careful not to remove them from the returned hash.
+_IMPORTANT_: `:count` and `:page` are the only 2 required Pagy core variables, so be careful not to remove them from the returned hash.
 
 See also the [How To](../how-to.md) wiki page for some usage example.
 
@@ -89,7 +89,7 @@ end
 
 **Notice**: in order to paginate arrays, you may want to use the  [array extra](../extras/array.md).
 
-## Writing your own pagy methods
+## Writing your own Pagy methods
 
 Somethimes you may need to paginate different kinds of collections (that require different overriding) in the same controller, so using one single `pagy` method would not be an option.
 
@@ -111,7 +111,7 @@ def pagy_another_custom(collection, vars={})
   vars = { count: collection.count(:all),
            page:  params[vars[:page_param]||VARS[:page_param]] }.merge!(vars)
   pagy = Pagy.new(vars)
-  # return the pagy instance and the paginated items
+  # return the Pagy instance and the paginated items
   return pagy, collection.offset(pagy.offset).limit(pagy.limit)
 end
 ```

docs/api/frontend.md

@@ -30,11 +30,11 @@ use some of its method in some view:
 
 All the methods in this module are prefixed with the `"pagy_"` string in order to avoid any possible conflict with your own methods when you include the module in your helper. The methods prefixed with the `"pagy_get_"` string are sub-methods/getter methods that are intended to be overridden and not used directly.
 
-Please, keep in mind that overriding any method is very easy with pagy. Indeed you can do it right where you are using it: no need of monkey-patching or subclassing or tricky gymnic.
+Please, keep in mind that overriding any method is very easy with Pagy. Indeed you can do it right where you are using it: no need of monkey-patching or tricky gymnic.
 
 ### pagy_nav(pagy)
 
-This method takes the pagy object and returns the HTML string with the pagination links, which are wrapped in a `nav` tag and are ready to use in your view. For example:
+This method takes the Pagy object and returns the HTML string with the pagination links, which are wrapped in a `nav` tag and are ready to use in your view. For example:
 
 ```erb
 <%== pagy_nav(@pagy) %>
@@ -101,13 +101,13 @@ This method returns a specialized proc that you call to produce the page links.
 Here is how you should use it: in your helper or template call the method to get the proc (just once):
 
 ```ruby
-link = pagy_link_proc( pagy [, extra_attributes_string ])
+link = pagy_link_proc( pagy [, extra_attributes_string ] )
 ```
 
 Then call the `"link"` proc to get the links (multiple times):
 
 ```ruby
-link.call( page_number [, text [, extra_attributes_string ]])
+link.call( page_number [, text [, extra_attributes_string ] ] )
 ```
 
 ### Extra attribute strings
@@ -125,7 +125,7 @@ If you need to add some HTML attribute to the page links, you can pass some extr
     link.call(2)
     #=> <a href="...?page=2" data-remote="true">2</a>
     ```
-2. For one pagy object: pass the `:link_extra` variable to a pagy constructor (`Pagy.new` or `pagy` controller method):
+2. For one Pagy object: pass the `:link_extra` variable to a Pagy constructor (`Pagy.new` or `pagy` controller method):
     ```ruby
     # in any controller
     @pagy, @records = pagy(my_scope, link_extra: 'data-remote="true"')
@@ -158,17 +158,17 @@ This method is similar to the `I18n.t` and its equivalent rails `t` helper. It i
 
 ## I18n
 
-Pagy is I18n ready. That means that all the UI strings that pagy uses are stored in a [dictionaray YAML file](https://github.com/ddnexus/pagy/blob/master/lib/locales/pagy.yml), ready to be customized and/or translated/pluralized.
+Pagy is I18n ready. That means that all the UI strings that Pagy uses are stored in a [dictionaray YAML file](https://github.com/ddnexus/pagy/blob/master/lib/locales/pagy.yml), ready to be customized and/or translated/pluralized.
 
 The YAML file is available at `Pagy.root.join('locales', 'pagy.yml')`. It contains a few entries used in the the UI by helpers and templates through the [pagy_t method](#pagy_tpath-vars) (eqivalent to the `I18n.t` or rails `t` helper).
 
-By default, the `pagy_t` method uses the pagy implementation of I18n, which does not depend on the `I18n` gem in any way. It's _5x faster_ and uses _3.5x less memory_, but it provides only pluralization/interpolation without translation, so it's only useful with single language apps (i.e. only `fr` or only `en` or only ...)
+By default, the `pagy_t` method uses the Pagy implementation of I18n, which does not depend on the `I18n` gem in any way. It's _5x faster_ and uses _3.5x less memory_, but it provides only pluralization/interpolation without translation, so it's only useful with single language apps (i.e. only `fr` or only `en` or only ...)
 
 If you need full blown I18n, you should require the `i18n` extra, which will override the `pagy_t` method to use directly `::I18n.t`.
 
 ### Pagy::Frontend::I18N Constant
 
-The `Pagy::Frontend::I18N` constant is the core of the pagy I18n implementation. It has no effect if you use the `i18n` extra (which uses the `I18n.t` method directly). This constant allows to control the dictionary file to load and the pluralization proc.
+The `Pagy::Frontend::I18N` constant is the core of the Pagy I18n implementation. It has no effect if you use the `i18n` extra (which uses the `I18n.t` method directly). This constant allows to control the dictionary file to load and the pluralization proc.
 
 #### Pagy::Frontend::I18N.load_file(file)
 

docs/api/pagy.md

@@ -53,7 +53,7 @@ This method returns the `pathname` of the `pagy/lib` root dir. It is useful to g
 
 ### Pagy.new
 
-_Notice_: If you use the `Pagy::Backend` its `pagy` method will instantiate and return the pagy object for you.
+_Notice_: If you use the `Pagy::Backend` its `pagy` method will instantiate and return the Pagy object for you.
 
 The `Pagy.new` method accepts a single hash of variables that will be merged with the `Pagy::Vars` hash and will be used to create the object. The only mandatory variable is the `:count` of the collection to paginate: all the other variables are optional and have sensible defaults. Of course you will also have to pass the `page` or you will always get the default page number 1.
 
@@ -109,6 +109,8 @@ Pagy exposes all the instance variables needed for the pagination through a few
 
 This method is the core of the pagination. It returns an array containing the page numbers and the `:gap` items to be rendered with the navigation links (e.g. `[1, :gap, 7, 8, "9", 10, 11, :gap, 36]`). It accepts an optional `size` argument (only useful for extras), defaulted on the `:size` variable.
 
+**Notice**: A `:gap` is added only where the series is missing at least two pages. When the series is missing only one page, the `:gap` is replaced with the page link of the actual missing page. That's because the page link uses the same space of the `...` gap but it is more useful.
+
 The nav helpers and the templates basically loop through this array and render the correct item by simply checking its type:
 
 - if the item is an `Integer` then it is a page link
@@ -119,7 +121,7 @@ That is self-contained, simple and efficient.
 
 ### Lowest limit analysys
 
-The lowest possible limit of the pagination is reached when the collection has `0` count. In that case the pagy object created has the following peculiar attributes:
+The lowest possible limit of the pagination is reached when the collection has `0` count. In that case the Pagy object created has the following peculiar attributes:
 
 | Attribute | Value   |
 | --------- | ------- |

docs/extras/i18n.md

@@ -3,7 +3,7 @@ title: I18n
 ---
 # I18n Extra
 
-The `I18n` extra overrides the `pagy_t` method so it uses `I18n.t`. Use this extra only with multi-language apps since the `I18n` gem adds quite an overhead and slowers down pagy.
+The `I18n` extra overrides the `pagy_t` method so it uses `I18n.t`. Use this extra only with multi-language apps since the `I18n` gem adds quite an overhead and slowers down Pagy.
 
 See also [I18n](../api/frontend.md#i18n).
 

docs/extras/responsive.md

@@ -17,7 +17,7 @@ See [extras](../extras.md) for general usage info.
 # in the initializer
 require 'pagy/extra/responsive'
 
-# set your default custom breakpoints (width/size pairs) globally (it can be overridden per pagy instance)
+# set your default custom breakpoints (width/size pairs) globally (it can be overridden per Pagy instance)
 Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]}
 
 # in rails apps: add the assets-path
@@ -50,18 +50,18 @@ This extra is composed of 2 small files:
 
 ### :breakpoints
 
-The `:breakpoint` variable is a pagy variable added by the `responsive` extra: it allows you to control how the page links will get shown at different widths. It is a hash where the keys are integers representing the breakpoint widths in pixels and the values are the pagy `:size` variables to be applied for that width.
+The `:breakpoint` variable is a non-core variable added by the `responsive` extra: it allows you to control how the page links will get shown at different widths. It is a hash where the keys are integers representing the breakpoint widths in pixels and the values are the Pagy `:size` variables to be applied for that width.
  For example:
 
 ```ruby
 Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]}
 ```
 
-The above statement means that from `0` to `450` pixels width, pagy will use the `[1,2,2,1]` size, from `450` to `750` it will use the `[3,4,4,3]` size and over `750` it will use the `[4,5,5,4]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section)
+The above statement means that from `0` to `450` pixels width, Pagy will use the `[1,2,2,1]` size, from `450` to `750` it will use the `[3,4,4,3]` size and over `750` it will use the `[4,5,5,4]` size. (Read more about the `:size` variable in the [How to control the page links](../how-to.md#controlling-the-page-links) section)
 
 **IMPORTANT**: You can set any number of breakpoints with any arbitrary width and size. The only requirement is that the `:breakpoints` hash must contain always the `0` size. An `ArgumentError` exception will be raises if it is missing.
 
-**Notice**: Each breakpoint added slowers down pagy of almost 10%. For example: with 5 breakpoints (which are actually quite a lot) the nav will be rendered rougly in twice the normal time. However, that will still run about 15 times faster than Kaminari and 6 times faster than WillPaginate.
+**Notice**: Each breakpoint added slowers down Pagy of almost 10%. For example: with 5 breakpoints (which are actually quite a lot) the nav will be rendered rougly in twice the normal time. However, that will still run about 15 times faster than Kaminari and 6 times faster than WillPaginate.
 
 ## Methods
 
@@ -71,7 +71,7 @@ The `reponsive` extra adds an instance method to the `Pagy` class and couple of
 
 **Notice**: Unless you are going to override a `pagy_nav_responsive` or `pagy_nav_bootstrap_responsive` helper you can ignore this method.
 
-This is a `Pagy` instance method that returns the data structure used by the `pagy_nav_responsive` and `pagy_nav_bootstrap_responsive` helpers in order to build the html and the javascript codes needed to make pagy responsive to different widths.
+This is a `Pagy` instance method that returns the data structure used by the `pagy_nav_responsive` and `pagy_nav_bootstrap_responsive` helpers in order to build the html and the javascript codes needed to make Pagy responsive to different widths.
 
 ### pagy_nav_responsive(pagy, ...)