search

kasei / attean

A Perl Semantic Web Framework
19 stars 10 forks source link

Attean::QueryPlanner synopsis contains incomplete code #94

Closed jonassmedegaard closed 8 years ago

jonassmedegaard commented 8 years ago

Last line of Attean::QueryPlanner synopsis contains reference to undeclared variable $e.

kasei commented 8 years ago

I'm fixing this as that line is obviously a mistake, but the nature of the synopsis means that there will be other undeclared variables (like $model). Does the rest of the synopsis make enough sense to you to leave it as-is?

jonassmedegaard commented 8 years ago

Quoting Gregory Todd Williams (2016-05-03 17:12:43)

I'm fixing this as that line is obviously a mistake, but the nature of the synopsis means that there will be other undeclared variables (like $model). Does the rest of the synopsis make enough sense to you to leave it as-is?

Yes, rest makes sense.

I suggest you reconsider regarding the need for synopsis to be working code - and consider use Test::Synopsis.

kasei commented 8 years ago

I'll consider it in places, but for many of the modules in Attean, I suspect you'd end up with a synopsis that was >90% setup code that is irrelevant (or at least orthogonal) to showing how to use the module's API. I'm not sure that's a good trade-off (though I'll listen if you or anyone else wants to try to convince me).