squashme: add godoc, update README, rename struct

Author: bfabio

README.md

@@ -16,22 +16,35 @@ This parser performs syntactic and semantic validation according to the
 
 - Go library and CLI tool (`publiccode-parser`)
 - Supports the latest version of the `publiccode.yml` Standard
-- `publiccode-parser` can output validation errors as JSON or in [errorformat](https://vim-jp.org/vimdoc-en/quickfix.html#error-file-format) friendly way
-- Verifies the existence of URLs by checking the response for URL fields (can be disabled)
+- `publiccode-parser` can output validation errors as JSON or in a
+  [errorformat](https://vim-jp.org/vimdoc-en/quickfix.html#error-file-format)
+  friendly way
+- Verifies the existence of URLs by checking the response for URL fields
+  (can be disabled)
 
 ## Example
 
 ```go
-parser := publiccode.NewParser("file:///path/to/local/dir/publiccode.yml")
-// OR
-// parser := publiccode.NewParser("https://github.com/example/example/publiccode.yml")
-
-// all these settings are optional:
-parser.DisableNetwork = true
-parser.Branch = "mybranch"
+parser, err := NewDefaultParser()
+if err != nil {
+   // handle errors
+}
 
-err := parser.Parse()
-publiccode := parser.PublicCode
+publicCode, err := parser.Parse("https://foobar.example.org/publiccode.yml")
+// OR
+// publicCode, err := parser.Parse("file:///path/to/local/dir/publiccode.yml")
+if err != nil {
+    // handle errors
+}
+
+if publicCode != nil {
+    switch pc := publicCode.(type) {
+    case *publiccode.V0:
+        fmt.Println(pc)
+    default:
+        // handle error
+    }
+}
 ```
 
 ## Validation from command line

fields.go

@@ -16,7 +16,7 @@ type validateFn func (publiccode PublicCode, parser Parser, network bool) error
 // with a simple YAML schema.
 // It returns any error encountered as ValidationResults.
 func validateFieldsV0(publiccode PublicCode, parser Parser, network bool) error {
-	publiccodev0 := publiccode.(PublicCodeV0)
+	publiccodev0 := publiccode.(V0)
 
 	var vr ValidationResults
 	var err error

parser.go

@@ -22,8 +22,9 @@ import (
 	urlutil "github.com/italia/publiccode-parser-go/v4/internal"
 )
 
+// ParserConfig defines the configuration options for the Parser
 type ParserConfig struct {
-	// DisableNetwork disables all network tests (URL existence and Oembed). This
+	// DisableNetwork disables all network tests (fe. URL existence and Oembed). This
 	// results in much faster parsing.
     DisableNetwork bool
 
@@ -35,7 +36,9 @@ type ParserConfig struct {
 	// in the publiccode.yml
     Branch string
 
-	// TODO: doc
+	// The path or URL used as base of relative files in publiccode.yml (eg. logo). If
+	// given, it will be used for existence checks and such, instead of the `url` key
+	// in the publiccode.yml file
 	BaseURL string
 }
 
@@ -44,10 +47,7 @@ type Parser struct {
 	disableNetwork bool
 	domain         Domain
 	branch         string
-
-	// The URL used as base of relative files in publiccode.yml (eg. authorsFile)
-	// It can be a local file with the 'file' scheme.
-	baseURL *url.URL
+	baseURL        *url.URL
 }
 
 // Domain is a single code hosting service.
@@ -58,8 +58,21 @@ type Domain struct {
 	BasicAuth   []string `yaml:"basic-auth"`
 }
 
-// NewParser initializes a new Parser object and returns it.
-// TODO
+// NewParser creates and returns a new Parser instance based on the provided ParserConfig.
+//
+// It returns a pointer to the newly created Parser, if successful, and an error.
+// The error is non-nil if there was an issue initializing the Parser.
+//
+// Example usage:
+//
+//  config := ParserConfig{
+//      DisableNetwork: true
+//  }
+//  parser, err := NewParser(config)
+//  if err != nil {
+//      log.Fatalf("Failed to create parser: %v", err)
+//  }
+//  // Use parser...
 func NewParser(config ParserConfig) (*Parser, error) {
 	parser := Parser{
 		disableNetwork: config.DisableNetwork,
@@ -77,11 +90,57 @@ func NewParser(config ParserConfig) (*Parser, error) {
 	return &parser, nil
 }
 
+// NewDefaultParser creates and returns a new Parser instance, using the default config.
+//
+// It returns a pointer to the newly created Parser, if successful, and an error.
+// The error is non-nil if there was an issue initializing the Parser.
+//
+// The default config is ParserConfig's fields zero values.
+//
+// Example usage:
+//
+//  parser, err := NewDefaultParser()
+//  if err != nil {
+//      log.Fatalf("Failed to create parser: %v", err)
+//  }
+//  // Use parser...
 func NewDefaultParser() (*Parser, error) {
 	return NewParser(ParserConfig{})
 }
 
-// ParseStream reads the data and tries to parse it. Returns an error if fails.
+// ParseStream reads from the provided io.Reader and attempts to parse the input
+// stream into a PublicCode object.
+//
+// Returns a non-nil error if there is an issue with the parsing process and a
+// a struct implementing the Publiccode interface, depending on the version
+// of the publiccode.yml file parsed.
+//
+// The only possible type returned is V0, representing v0.* files.
+//
+// PublicCode can be nil when there are major parsing issues.
+// It can also be non-nil even in presence of errors: in that case the returned struct
+// is filled as much as possible, based on what is successful parsed.
+//
+// Example usage:
+//
+//  file, err := os.Open("publiccode.yml")
+//  if err != nil {
+//      log.Fatalf("Failed to open file: %v", err)
+//  }
+//  defer file.Close()
+//
+//  publicCode, err := parser.ParseStream(file)
+//  if err != nil {
+//      log.Printf("Parsing errors: %v", err)
+//  }
+//  if publicCode != nil {
+//      switch pc := publicCode.(type) {
+//      case *publiccode.V0:
+//          fmt.Println(pc)
+//      default:
+//          log.Println("PublicCode parsed, but unexpected type found.")
+//      }
+//  }
 func (p *Parser) ParseStream(in io.Reader) (PublicCode, error) {
 	b, err := io.ReadAll(in)
 	if err != nil {
@@ -146,13 +205,13 @@ func (p *Parser) ParseStream(in io.Reader) (PublicCode, error) {
 	var decodeResults ValidationResults
 
 	if version.Value[0] == '0' {
-		v0 := PublicCodeV0{}
+		v0 := V0{}
 		validateFields = validateFieldsV0
 
 		decodeResults = decode(b, &v0, node)
 		publiccode = v0
 	} else {
-		v1 := PublicCodeV1{}
+		v1 := V1{}
 		validateFields = validateFieldsV1
 
 		decodeResults = decode(b, &v1, node)
@@ -200,7 +259,7 @@ func (p *Parser) ParseStream(in io.Reader) (PublicCode, error) {
 			// TODO: find a cleaner way
 			key := strings.Replace(
 				err.Namespace(),
-				fmt.Sprintf("PublicCodeV%d.", publiccode.Version()),
+				fmt.Sprintf("V%d.", publiccode.Version()),
 				"",
 				1,
 			)
@@ -262,6 +321,34 @@ func (p *Parser) ParseStream(in io.Reader) (PublicCode, error) {
 	return publiccode, ve
 }
 
+// Parse reads from the provided uri and attempts to parse it into
+// a PublicCode object.
+//
+// Returns a non-nil error if there is an issue with the parsing process and a
+// a struct implementing the Publiccode interface, depending on the version
+// of the publiccode.yml file parsed.
+//
+// The only possible type returned is V0, representing v0.* files.
+//
+// PublicCode can be nil when there are major parsing issues.
+// It can also be non-nil even in presence of errors: in that case the returned struct
+// is filled as much as possible, based on what is successful parsed.
+//
+// Example usage:
+//
+//  // publicCode, err := parser.Parse("file:///app/publiccode.yml")
+//  publicCode, err := parser.Parse("https://foobar.example.org/publiccode.yml")
+//  if err != nil {
+//      log.Printf("Parsing errors: %v", err)
+//  }
+//  if publicCode != nil {
+//      switch pc := publicCode.(type) {
+//      case *publiccode.V0:
+//          fmt.Println(pc)
+//      default:
+//          log.Println("PublicCode parsed, but unexpected type found.")
+//      }
+//  }
 func (p *Parser) Parse(uri string) (PublicCode, error) {
 	var stream io.Reader
 
@@ -410,7 +497,7 @@ func decode[T any](data []byte, publiccode *T, node yaml.Node) ValidationResults
 	return ve
 }
 
-// TODO doc
+// Turn the input into a valid URL
 func toURL(file string) (*url.URL, error) {
 	if _, u := urlutil.IsValidURL(file); u != nil {
 		return u, nil

publiccode.go

@@ -1,6 +1,6 @@
 package publiccode
 
-// SupportedVersions lists the publiccode.yml versions this parser supports.
+// SupportedVersions contains the publiccode.yml versions this parser supports.
 var SupportedVersions = []string{"0.2", "0.2.0", "0.2.1", "0.2.2", "0.3", "0.3.0"}
 
 type PublicCode interface {

v0.go

@@ -6,8 +6,8 @@ import (
 	urlutil "github.com/italia/publiccode-parser-go/v4/internal"
 )
 
-// PublicCode is a publiccode.yml file definition.
-type PublicCodeV0 struct {
+// V0 represents a publiccode.yml v0.*
+type V0 struct {
 	PubliccodeYamlVersion string `yaml:"publiccodeYmlVersion" validate:"required,oneof=0.2 0.2.0 0.2.1 0.2.2 0.3 0.3.0"`
 
 	Name             string   `yaml:"name" validate:"required"`
@@ -142,15 +142,15 @@ type ITSectionV0 struct {
 	} `yaml:"piattaforme"`
 }
 
-func (p PublicCodeV0) Version() uint {
+func (p V0) Version() uint {
 	return 0;
 }
 
-func (p PublicCodeV0) ToYAML() ([]byte, error) {
+func (p V0) ToYAML() ([]byte, error) {
 	return yaml.Marshal(p)
 }
 
-func (p PublicCodeV0) Url() *URL {
+func (p V0) Url() *URL {
 	if p.URL == nil {
 		return nil
 	}

v1.go

@@ -6,8 +6,7 @@ import (
 	urlutil "github.com/italia/publiccode-parser-go/v4/internal"
 )
 
-// PublicCode is a publiccode.yml file definition.
-type PublicCodeV1 struct {
+type V1 struct {
 	PubliccodeYamlVersion string `yaml:"publiccodeYmlVersion" validate:"required,oneof=1.0 1.0.0"`
 
 	Name             string   `yaml:"name" validate:"required"`
@@ -138,15 +137,15 @@ type ITSectionV1 struct {
 	} `yaml:"piattaforme"`
 }
 
-func (p PublicCodeV1) Version() uint {
+func (p V1) Version() uint {
 	return 1;
 
 }
-func (p PublicCodeV1) ToYAML() ([]byte, error) {
+func (p V1) ToYAML() ([]byte, error) {
 	return yaml.Marshal(p)
 }
 
-func (p PublicCodeV1) Url() *URL {
+func (p V1) Url() *URL {
 	if p.URL == nil {
 		return nil
 	}