semver: document all pub functions (#8586)

vlib/semver/semver.v

@@ -2,7 +2,7 @@
 module semver
 
 // * Structures.
-// Structure representing version in semver format.
+// `Version` represents a semantic version in semver format.
 pub struct Version {
 pub:
 	major      int
@@ -12,7 +12,7 @@ pub:
 	metadata   string
 }
 
-// Enum representing type of version increment.
+// Increment represents the different types of version increments.
 pub enum Increment {
 	major
 	minor
@@ -20,7 +20,7 @@ pub enum Increment {
 }
 
 // * Constructor.
-// from returns Version structure parsed from input string.
+// from returns a `Version` structure parsed from `input` `string`.
 pub fn from(input string) ?Version {
 	if input.len == 0 {
 		return error('Empty input')
@@ -32,49 +32,68 @@ pub fn from(input string) ?Version {
 	return version
 }
 
-// build returns Version structure with given major, minor and patch versions.
+// build returns a `Version` structure with given `major`, `minor` and `patch` versions.
 pub fn build(major int, minor int, patch int) Version {
 	// TODO Check if versions are greater than zero.
 	return Version{major, minor, patch, '', ''}
 }
 
 // * Transformation.
-// increment returns Version structure with incremented values.
+// increment returns a `Version` structure with incremented values.
 pub fn (ver Version) increment(typ Increment) Version {
 	return increment_version(ver, typ)
 }
 
 // * Comparison.
+// satisfies returns `true` if the `input` expression can be validated to `true`
+// when run against this `Version`.
+// Example: assert semver.build(1,0,0).satisfies('<=2.0.0') == true
+// Example: assert semver.build(1,0,0).satisfies('>=2.0.0') == false
 pub fn (ver Version) satisfies(input string) bool {
 	return version_satisfies(ver, input)
 }
 
+// eq returns `true` if `v1` is equal to `v2`.
 pub fn (v1 Version) eq(v2 Version) bool {
 	return compare_eq(v1, v2)
 }
 
+// gt returns `true` if `v1` is greater than `v2`.
 pub fn (v1 Version) gt(v2 Version) bool {
 	return compare_gt(v1, v2)
 }
 
+// lt returns `true` if `v1` is less than `v2`.
 pub fn (v1 Version) lt(v2 Version) bool {
 	return compare_lt(v1, v2)
 }
 
+// ge returns `true` if `v1` is greater than or equal to `v2`.
 pub fn (v1 Version) ge(v2 Version) bool {
 	return compare_ge(v1, v2)
 }
 
+// le returns `true` if `v1` is less than or equal to `v2`.
 pub fn (v1 Version) le(v2 Version) bool {
 	return compare_le(v1, v2)
 }
 
 // * Utilites.
+// coerce converts the `input` version to a `Version` struct.
+// coerce will strip any contents *after* the parsed version string:
+/*
+Example:
+import semver
+v := semver.coerce('1.3-RC1-b2') or { semver.Version{} }
+assert v.satisfies('>1.0 <2.0') == true // 1.3.0
+*/
 pub fn coerce(input string) ?Version {
 	ver := coerce_version(input) or { return error('Invalid version for input "$input"') }
 	return ver
 }
 
+// is_valid returns `true` if the `input` `string` can be converted to
+// a  (semantic) `Version` struct.
 pub fn is_valid(input string) bool {
 	return is_version_valid(input)
 }