docs: updated ROADMAP, quick index (#104)

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

.mdsf.json

@@ -60,7 +60,8 @@ Feedback, contributions and proposals are welcome.
 
 > **Recent news**
 >
-> ✅ Preparing v2.5.0: new features, a few fixes (`EventuallyWithT`)
+> ✅ Preparing v2.5.0: new features: support for synctest, NoFileDescriptorLeak for macos,
+> plus a few fixes (`EventuallyWithT`, `Subset`).
 >
 > See also our [ROADMAP][doc-roadmap].
 

README.md

@@ -6,7 +6,7 @@ This policy outlines the commitment and practices of the go-openapi maintainers
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.2.x   | :white_check_mark: |
+| 2.4.x   | :white_check_mark: |
 
 ## Vulnerability checks in place
 

SECURITY.md

@@ -184,7 +184,7 @@ func (d *DocGenerator) buildIndexDocument(docsByDomain iter.Seq2[string, model.D
 	}
 
 	doc.RefCount = len(doc.Index)
-	doc.Metrics = buildMetrics(docsByDomain)
+	doc.Metrics = d.buildMetrics(docsByDomain)
 	doc.QuickIndex = buildQuickIndex(docsByDomain)
 
 	return doc
@@ -209,7 +209,7 @@ func buildIndexEntries(docsByDomain iter.Seq2[string, model.Document]) []model.I
 	return entries
 }
 
-func buildMetrics(docsByDomain iter.Seq2[string, model.Document]) (metrics model.Metrics) {
+func (d *DocGenerator) buildMetrics(docsByDomain iter.Seq2[string, model.Document]) (metrics model.Metrics) {
 	metrics.ByDomain = make(map[string]model.DomainMetrics)
 
 	for domain, doc := range docsByDomain {
@@ -240,7 +240,28 @@ func buildMetrics(docsByDomain iter.Seq2[string, model.Document]) (metrics model
 		metrics.ByDomain[domain] = domainMetrics
 	}
 
-	metrics.NonGenerics = metrics.Functions - metrics.Generics
+	metrics.NonGenerics = metrics.Assertions - metrics.Generics
+	variantsMultiplier := 1
+	genericsVariantsMultiplier := 1
+
+	if d.ctx.enableForward {
+		variantsMultiplier++
+		if d.ctx.enableFormat {
+			variantsMultiplier++
+		}
+	}
+
+	if d.ctx.enableFormat {
+		variantsMultiplier++
+		genericsVariantsMultiplier++
+	}
+
+	metrics.PackageVariants = metrics.NonGenerics*variantsMultiplier + metrics.Generics*genericsVariantsMultiplier
+
+	// caveat: assume 2 target packages (not really available from options atm).
+	const generatedPackages = 2
+	metrics.TotalVariants = generatedPackages * metrics.PackageVariants
+	metrics.TotalFunctions = generatedPackages * (metrics.PackageVariants + metrics.Helpers + 1) // add the Assertion constructor.
 
 	return metrics
 }

codegen/internal/generator/doc_generator.go

@@ -13,15 +13,18 @@ All assertions are classified into **{{ .Domains }}** domains to help navigate t
 
 ## API metrics
 
-Counts for core functionality, excluding variants (formatted, forward, forward-formatted).
-
-| Kind                     | Count             |
-| ------------------------ | ----------------- |
-| All functions            | {{ .Functions }}  |
-| All core assertions      | {{ .Assertions }} |
-| Generic assertions       | {{ .Generics }}   |
-| Helpers (not assertions) | {{ .Helpers }}    |
-| Others                   | {{ .Others }}     |
+Counts for core functionality, and generated variants (formatted, forward, forward-formatted).
+
+| Kind                      | Count             | Note |
+| ------------------------- | ----------------- | ---- |
+| All core functions             | {{ .Functions }} | Maintained core |
+| All core assertions       | {{ .Assertions }} | Usage with `*testing.T` |
+| Generic assertions        | {{ .Generics }}   | Type-safe assertions ("T" suffix) |
+| Helpers (not assertions)  | {{ .Helpers }}    | General-purpose utilities, not assertions |
+| Others                    | {{ .Others }}     | |
+| assert/require variants   | {{ .PackageVariants }} | Generated variants |
+| Total assertions variants | {{ .TotalVariants }} | Available assertions API |
+| Total API surface         | {{ .TotalFunctions }} | |
 
 {{- end }}
 

codegen/internal/generator/templates/doc_metrics.md.gotmpl

@@ -151,14 +151,17 @@ type IndexEntry struct {
 
 //nolint:tagliatelle // not using camelcase
 type Metrics struct {
-	Domains     int                      `yaml:"domains"`
-	Functions   int                      `yaml:"functions"`
-	Assertions  int                      `yaml:"assertions"`
-	Generics    int                      `yaml:"generics"`
-	NonGenerics int                      `yaml:"nongeneric_assertions"`
-	Helpers     int                      `yaml:"helpers"`
-	Others      int                      `yaml:"others"`
-	ByDomain    map[string]DomainMetrics `yaml:"by_domain"`
+	Domains         int                      `yaml:"domains"`
+	Functions       int                      `yaml:"functions"`
+	Assertions      int                      `yaml:"assertions"`
+	Generics        int                      `yaml:"generics"`
+	NonGenerics     int                      `yaml:"nongeneric_assertions"`
+	Helpers         int                      `yaml:"helpers"`
+	Others          int                      `yaml:"others"`
+	ByDomain        map[string]DomainMetrics `yaml:"by_domain"`
+	PackageVariants int                      `yaml:"package_variants"`
+	TotalVariants   int                      `yaml:"total_variants"`
+	TotalFunctions  int                      `yaml:"total_functions"`
 }
 
 type DomainMetrics struct {

codegen/internal/model/documentation.go

@@ -11,15 +11,18 @@ All assertions are classified into **19** domains to help navigate the API, depe
 
 ## API metrics
 
-Counts for core functionality, excluding variants (formatted, forward, forward-formatted).
+Counts for core functionality, and generated variants (formatted, forward, forward-formatted).
 
-| Kind                     | Count             |
-| ------------------------ | ----------------- |
-| All functions            | 135  |
-| All core assertions      | 131 |
-| Generic assertions       | 50   |
-| Helpers (not assertions) | 4    |
-| Others                   | 0     |
+| Kind                      | Count             | Note |
+| ------------------------- | ----------------- | ---- |
+| All core functions             | 135 | Maintained core |
+| All core assertions       | 131 | Usage with `*testing.T` |
+| Generic assertions        | 50   | Type-safe assertions ("T" suffix) |
+| Helpers (not assertions)  | 4    | General-purpose utilities, not assertions |
+| Others                    | 0     | |
+| assert/require variants   | 424 | Generated variants |
+| Total assertions variants | 848 | Available assertions API |
+| Total API surface         | 858 | |
 
 ## Quick index
 

docs/doc-site/api/metrics.md

@@ -55,7 +55,7 @@ All these variants make up several hundreds functions, which poses a challenge f
 
 We have adopted code and documentation generation as a mean to mitigate this issue.
 
-#### Current (v2.3.0-unreleased)
+#### Current (v2.5.0-unreleased)
 
  1. Generic assertions (with type parameters): {{% siteparam "metrics.generics" %}} functions
  2. Non-generic assertions (with t T parameter, no type parameters): {{% siteparam "metrics.nongeneric_assertions" %}} functions
@@ -65,12 +65,11 @@ We have adopted code and documentation generation as a mean to mitigate this iss
 
  **Generated Functions**
 
- 1. Generic assertions: {{% siteparam "metrics.generated_generic" %}}
- 2. Non-generic assertions: {{% siteparam "metrics.generated_nongeneric" %}}
- 3. Helper functions: {{% siteparam "metrics.generated_helpers" %}}
- 4. Constructors: 2
+ 1. Generated variants in each package (assert/require): {{% siteparam "metrics.package_variants" %}}
+ 2. Helpers:  {{% siteparam "metrics.helpers" %}}
+ 3. Constructors: 2 (1 in assert, 1 in require)
 
- Total: {{% siteparam "metrics.generated_total" %}} functions
+ Overall: {{% siteparam "metrics.total_functions" %}} generated functions
 
 ## Architecture Overview
 

docs/doc-site/project/maintainers/ARCHITECTURE.md

@@ -4,7 +4,7 @@ params:
         functions: 135
         assertions: 131
         generics: 50
-        nongeneric_assertions: 85
+        nongeneric_assertions: 81
         helpers: 4
         others: 0
         by_domain:
@@ -65,3 +65,6 @@ params:
             yaml:
                 name: Yaml
                 count: 5
+        package_variants: 424
+        total_variants: 848
+        total_functions: 858