Re^3: Simple question about Inside-Out objects

[Herkum]

I have looked at both of them and the reason that I don't use them is the same reason that I don't use a lot of other 'good' modules, poor documentation.

While I understand that Class::Std is not the perfect for solving all the problems for InsideOut objects. The concepts well explained and the documentation is easier to understand. That is why I recommended it to blazar

[xdg]

the reason that I don't use them is the same reason that I don't use a lot of other 'good' modules, poor documentation

I'd welcome any constructive feedback on the documentation of Class::InsideOut. I've tried hard to make that documentation simple for those who just want it to work and keep separate the theoretical underpinnings and complexities. I'm sorry that you didn't find it to be helpful and would like to hear your thoughts on what would make it more useful to you.

I can be reached via dagolden at cpan dot org.

[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. :)

[Herkum]

I am sorry, I did not mean to come off as insulting, and your post was very well written, I wish I had put the time into it that you did.