search

kentnl / Dist-Zilla-Plugin-Git-NextVersion-Sanitized

Sanitize versions handed to you by Git::NextVersion
Other
0 stars 0 forks source link

Documention isn't clear #1

Open pwr22 opened 9 years ago

pwr22 commented 9 years ago

I can't tell exactly what this module does or how I should use it from the POD on MetaCPAN

kentfredric commented 9 years ago

Yeah, docs could do with a bit of improvement. The code in it is very minimal and just glues the sanitized role to Git::NextVersion, so any documentation I draft will be similar to this: https://metacpan.org/pod/Dist::Zilla::Plugin::RewriteVersion::Sanitized

Mostly, because of the fact its functionality is wholly dependent on its component modules, the documentation as such will have to be changed as either component is.

So... the redux is, reading : https://metacpan.org/pod/Dist::Zilla::Role::Version::Sanitize and https://metacpan.org/pod/Dist::Zilla::Plugin::Git::NextVersion and mentally smushing the two together will give you what you want to know.

pwr22 commented 9 years ago

I did read both of those before commenting, and maybe I am just stupid, but I still couldn't work out what I needed to

I was trying to workout how to get anything that isn't written \d+.\d+(_\d+)? rejected with an error. I've since realised I'm very unlikely to ever make a mistake here :D

But overall it might be indicative that the other docs could do with a cleanup. I'd advocate writing them more in a how-to manner that shows examples for potential use-cases

kentfredric commented 9 years ago

Ah. There's no proviso for that at present. The design is presently "Just fix this stuff and warn you if it needed fixing", because while you want it to error by design, I want it to be corrected by design.

ie: Its oriented so if I do V=2.5.0 then V=2.005000

vs being oriented so V=2.5.0 is an error.

But its not just "normalize", because it allows stipulating a fixed mantissa, so that if I wrote

V=2.005 , then V=2.005000 , not 2.005 ;)

If you can suggest a sane stricture that I could add that contends those concerns and yours I'd go for it, but it seems the purpose of this is orthogonal to what you want.

pwr22 commented 9 years ago

Ah, thanks for clarifying and now I think about it more its in the modules name! It says Sanitized not Validated