TODO list for discussion - Tasks that came to mind when writing/fixing the documentation

[abinoam]

Well,

I have already heard about documentation driven development.... I will not try to do that, but I can't deny that as I try to write more documentation or fix the current one some things naturally come to mind about HighLine.
I'll write them here to keep track of them and to discuss with anybody interested.

There's too much parameters at the constructor signature of Highline

  #
  # Create an instance of HighLine connected to the given _input_
  # and _output_ streams.
  #
  # @param input [IO] the default input stream for HighLine.
  # @param output [IO] the default output stream for HighLine.
  # @param wrap_at [Integer] all statements outputed through
  #   HighLine will be wrapped to this column size if set.
  # @param page_at [Integer] page size and paginating.
  # @param indent_size [Integer] indentation size in spaces.
  # @param indent_level [Integer] how deep is indentated.
  def initialize( input = $stdin, output = $stdout,
                  wrap_at = nil, page_at = nil, indent_size=3, indent_level=0 )

I think we could just use input and output as their core to HighLine class.
Perhaps use an additional and optional *options hash parameter and fetch from it.
Yield self to get more parameters? I don't see any use of this.

Change require 'highline/import' to somethig include HighLine to give direct access to ask and say

As I tried to document this behaviour properly with yard I saw that the comments sticked to the next class definition. In the case was Kernel.

# import.rb
#
# <tt>require "highline/import"</tt> adds shortcut methods to Kernel, making
# agree(), ask(), choose() and say() globally available.  This is handy for
# quick and dirty input and output.  These methods use the HighLine object in
# the global variable <tt>$terminal</tt>, which is initialized to used
# <tt>$stdin</tt> and <tt>$stdout</tt> (you are free to change this).
# Otherwise, these methods are identical to their HighLine counterparts, see that
# class for detailed explanations.
#
module Kernel
  extend Forwardable
  def_delegators :$terminal, :agree, :ask, :choose, :say
end

So it didn't make much sense. When I was trying to "fix" yard I thought about that this behaviour shouldn't be tied into "requiring an specific file" rather it should be tied to "including module to add additional funcionality"

Any comments, suggestions, etc?

I'll add more "tasks" as I progress with the docs.

cc: @JEG2 , @matugm, @djberg96,@practicingruby

[JEG2]

I think we could just use input and output as their core to HighLine class. Perhaps use an additional and optional *options hash parameter and fetch from it.

Another option might be to use keyword parameters for everything.

When I was trying to "fix" yard I thought about that this behaviour shouldn't be tied into "requiring an specific file" rather it should be tied to "including module to add additional funcionality"

This sounds very wise to me.

[abinoam]

Growing the todo list.
HighLine.find_or_create_style_list doesn't check if the compound styles are valid styles. Well, The whole styling thing is a little hard. Perhaps we should make a new api for the styles and for the "rendering" of the strings with such styles. But... for while, just taking this note for future review.

[djberg96]

@abinoam I agree with @JEG2 that the behavior to be tied to a module rather than a require.

[abinoam]

Thanks for your input @djberg96
I would appreciate any more comment, so feel free to write them! 👍