Re^5: Simple question about Inside-Out objects

[Anonymous Monk]

Very mature response to an otherwise insulting response. ++you.

The problem I have with any documentation is the case when I am presented with an example, but I have no knowledge of why I would need to understand that example, let alone if that example is even relevant to my needs. While I fully realize that the author can in no way be held responsible for being able to explain module usage to 100% of their readers -- you have to ask yourself at all times ... does this example make sense by itself?

And yes, it's OK if it doesn't.

But what if you can make it easier to understand anyways? What if you could write examples that progressively build up to them first. That is, don't introduce new concepts in the code snippet ... explain what the purpose is first. Here, take this quote from your docs:

Additional functions may be imported as usual by including them as arguments to use. For example:

  use Class::InsideOut qw( register public );
 
  public name => my %name;
 
  sub new { register( shift ) }

OK ... so I see that I can import functions into my class. But what do register and public mean? You say "that is not important right now, I will explain those later." Except you are not here to tell me that. Instead I now stop, and waste brain cells wondering when and why I would need to alter my constructor to use register.

Instead, I would have only used one line:

use Class::InsideOut qw( register public );

Don't show the usage for register and public until it is time to talk about them.

Another point -- your module seems to imply that the user needs to learn a new language subset, for example:

  public   name => my %name;
  readonly ssn  => my %ssn;
  private  age  => my %age;


  $name{ refaddr $self } = "James";
  $ssn { id      $self } = 123456789;
  $age { id      $self } = 32;

Instead of throwing these cryptic and seemingly unusable code snippets at the learner, maybe you should instead teach them the language first? "Hey?!? How come I don't gotta stick a comma between readonly and ssn?" :/

While I do not agree with Herkum's tact, I must confess that the docs are a bit daunting. I must also confess that I am not a supporter of Inside Out Objects, and have not bothered to read Damian's writings on them. If I had, perhaps your docs would seem more intuitive to me, but if your ulterior motive is to attract users -- you gotta dumb it down sell it man. :)