📝 Document Tag and Technology in Go code

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- json schemas for tags.yaml and technologies.yaml: all fields were wrongly marked as required
+
 ## [1.4.1] - 2024-04-17
 
 ### Added
@@ -107,8 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release
 
-[Unreleased]: https://github.com/ortfo/db/compare/v1.4.0...HEAD
-[1.4.1]: https://github.com/ortfo/db/-/releases/tag/v1.4.1
+[Unreleased]: https://github.com/ortfo/db/compare/v1.4.1...HEAD
+[1.4.1]: https://github.com/ortfo/db/compare/v1.4.0...v1.4.1
 [1.4.0]: https://github.com/ortfo/db/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/ortfo/db/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/ortfo/db/compare/v1.1.0...v1.2.0
@@ -120,5 +124,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.2.0]: https://github.com/ortfo/db/releases/tag/v0.2.0
 
 [//]: # (C3-2-DKAC:GGH:Rortfo/db:Tv{t})
-
-[unreleased]: https://github.com/ortfo/db/-/compare/v1.4.1...main

metadata.go

@@ -21,15 +21,25 @@ type autodetectData struct {
 	ContentConditions []string
 }
 
+// Tag represents a category that can be assigned to a work. See https://ortfo.org/db/tags for more information.
 type Tag struct {
+	// Singular-form name of the tag. For example, "Book".
 	Singular         string   `yaml:"singular"`
+	// Plural-form name of the tag. For example, "Books".
 	Plural           string   `yaml:"plural"`
 	Description      string   `yaml:"description,omitempty"`
+	// URL to a website where more information can be found about this tag.
 	LearnMoreAt      string   `yaml:"learn more at,omitempty"`
+	// Other singular-form names of tags that refer to this tag. The names mentionned here should not be used to define other tags.
 	Aliases          []string `yaml:"aliases,omitempty"`
+	// Various ways to automatically detect that a work is tagged with this tag.
 	DetectConditions struct {
+		// Consider the work to be tagged with this tag if it contains any of the files specified here. Glob patterns are supported.
+		// Files are searched relative to the work's folder (even in Scattered mode, files are not searched relative to the .ortfo folder)
 		Files    []string `yaml:"files,omitempty"`
+		// To be implemented
 		Search   []string `yaml:"search,omitempty"`
+		// Consider the work to be tagged with this tag if it was made with any of the technologies specified here.
 		MadeWith []string `yaml:"made with,omitempty"`
 	} `yaml:"detect,omitempty"`
 }
@@ -53,15 +63,22 @@ func (t Tag) Detect(ctx *RunContext, workId string, techs []Technology) (bool, e
 	}.Detect(ctx, workId)
 }
 
+// Technology represents a "technology" (in the very broad sense) that was used to create a work. See https://ortfo.org/db/technologies for more information.
 type Technology struct {
+	// The slug is a unique identifier for this technology, that's suitable for use in a website's URL.
+	// For example, the page that shows all works using a technology with slug "a" could be at https://example.org/technologies/a.
 	Slug        string `yaml:"slug"`
 	Name        string `yaml:"name"`
+	// Name of the person or organization that created this technology.
 	By          string `yaml:"by,omitempty"`
 	Description string `yaml:"description,omitempty"`
 
+	// URL to a website where more information can be found about this technology.
 	LearnMoreAt string `yaml:"learn more at,omitempty"`
 
+	// Other technology slugs that refer to this technology. The slugs mentionned here should not be used in the definition of other technologies.
 	Aliases []string `yaml:"aliases,omitempty"`
+
 	// Files contains a list of gitignore-style patterns. If the work contains any of the patterns specified, we consider that technology to be used in the work.
 	Files []string `yaml:"files,omitempty"`
 	// Autodetect contains an expression of the form 'CONTENT in PATH' where CONTENT is a free-form unquoted string and PATH is a filepath relative to the work folder.