Fix relation docs, simplify API reference links (#419)

Author: mlange-42

docs/content/concepts/index.md

@@ -45,7 +45,7 @@ When dealing with stored entities, it may be required to check whether they are
 {{< code-func concepts_test.go TestEntityAlive >}}
 
 In Ark, entities are returned to a pool when they are removed from the world.
-These entities can be recycled, with the same ID ({{< api ecs Entity.ID Entity.ID >}}), but an incremented generation ({{< api ecs Entity.Gen Entity.Gen >}}).
+These entities can be recycled, with the same ID ({{< api ecs Entity.ID >}}), but an incremented generation ({{< api ecs Entity.Gen >}}).
 This allows to determine whether an entity held by the user is still alive, despite it was potentially recycled.
 
 ## Components

docs/content/relations/index.md

@@ -34,7 +34,7 @@ for relations with different target entities.
 
 ## Relation components
 
-To use entity relations, create components that have *embedded* an {{< api ecs RelationMarker >}} as their first member:
+To use entity relations, create components that have *embedded* a {{< api ecs RelationMarker >}} as their first member:
 
 ```go
 type ChildOf struct {
@@ -48,11 +48,12 @@ The component can contain further variables, but the marker must be the first on
 ## Creating relations
 
 Most methods of `MapX` (e.g. {{< api ecs Map2 >}}) provide var-args for specifying relationship targets.
-These are of type {{< api Relation >}}, which is an interface with multiple implementations:
+These are of type {{< api ecs Relation >}}, which specifies a component type and a target entity.
+There are multiple constructors for {{< api ecs Relation >}}:
 
-{{< api Rel >}} is safe, but has some run-time overhead for component ID lookup.
-
-{{< api RelIdx >}} is fast but more error-prone.
+- {{< api ecs Rel >}} uses a generic type parameter to identify the component. It is safe, but has some run-time overhead for component ID lookup on first usage.
+- {{< api ecs RelIdx >}} uses an index to identify the component. It is fast but more error-prone.
+- {{< api ecs RelID >}} uses a component ID. It is for use with the [unsafe API](../unsafe/).
 
 See the examples below for their usage.
 
@@ -62,10 +63,10 @@ When creating entities, we can use a `MapX` (e.g. {{< api ecs Map2.NewEntity >}}
 
 {{< code-func relations_test.go TestNewEntity >}}
 
-For the faster variant {{< api RelIdx >}}, note that the first argument
+For the faster variant {{< api ecs RelIdx >}}, note that the first argument
 is the zero-based index of the relation component in the {{< api ecs Map2 >}}'s generic parameters.
 
-If there are multiple relation components, multiple {{< api Rel >}}/{{< api RelIdx >}} arguments can (and must) be used.
+If there are multiple relation components, multiple {{< api ecs Rel >}}/{{< api ecs RelIdx >}} arguments can (and must) be used.
 
 ### When adding components
 
@@ -115,9 +116,9 @@ For short-lived targets, it is better to pass them when building a query with {{
 
 These targets are not cached, but the same filter can be used for different targets.
 
-Filters also support both {{< api Rel >}} and {{< api RelIdx >}}.
-In the filter examples above, we used the slow but safe {{< api Rel >}} when building the filter.
-When getting the query, we use the faster {{< api RelIdx >}},
+Filters also support both {{< api ecs Rel >}} and {{< api ecs RelIdx >}}.
+In the filter examples above, we used the slow but safe {{< api ecs Rel >}} when building the filter.
+When getting the query, we use the faster {{< api ecs RelIdx >}},
 because in real-world use cases this is called more frequently than the one-time filter construction.
 
 Relation targets not specified by the filter are treated as wildcard.
@@ -180,4 +181,4 @@ to represent animals of different species in multiple farms.
 {{< code relations_example_test.go >}}
 
 Note that this examples uses the safe and clear, but slower generic variant to specify relationship targets.
-As an optimization, {{< api RelIdx >}} could be used instead of {{< api Rel >}}, particularly for queries.
+As an optimization, {{< api ecs RelIdx >}} could be used instead of {{< api ecs Rel >}}, particularly for queries.

docs/content/stats/index.md

@@ -36,25 +36,25 @@ Archetype -- Tables:    1, Comps:  2, Entities:    100, Cap:   1024, Mem:    32.
 
 ## World stats
 
-{{< api "ecs/stats" World stats.World >}} provides world information like a list of all component types
+{{< api "ecs/stats" World >}} provides world information like a list of all component types
 and the total memory reserved for entities and components.
-Further, it contains {{< api "ecs/stats" Entities stats.Entities >}} and
-a {{< api "ecs/stats" Archetype stats.Archetype >}} for each archetype.
+Further, it contains {{< api "ecs/stats" Entities >}} and
+a {{< api "ecs/stats" Archetype >}} for each archetype.
 
 ## Entity stats
 
-{{< api "ecs/stats" Entities stats.Entities >}} contains information about the entity pool,
+{{< api "ecs/stats" Entities >}} contains information about the entity pool,
 like capacity, alive entities and available entities for recycling.
 
 ## Archetype stats
 
-{{< api "ecs/stats" Archetype stats.Archetype >}} provides information about an archetype, like its components,
+{{< api "ecs/stats" Archetype >}} provides information about an archetype, like its components,
 memory in total and per entity, and more state information.
 
-Further, it contains a {{< api "ecs/stats" Table stats.Table >}} for each table.
+Further, it contains a {{< api "ecs/stats" Table >}} for each table.
 
 ## Table stats
 
-{{< api "ecs/stats" Table stats.Table >}} contains size, capacity and memory information for a table.
+{{< api "ecs/stats" Table >}} contains size, capacity and memory information for a table.
 Tables are used to represent sub-archetypes with the same components, but a different combination
 of [relationship](../relations) targets.

docs/layouts/shortcodes/api.html

@@ -1,9 +1,14 @@
 {{- $pkg := .Get 0 -}}
-{{- $text := (replace $pkg "/" ".") -}}
+{{- $text := (replace $pkg "ecs/" "") -}}
+{{- $text := (replace $text "ecs" "") -}}
 {{- $link := $pkg -}}
 {{- if .Get 1 -}}
     {{- $mem := .Get 1 -}}
-    {{- $text = printf "%s.%s" $text $mem -}}
+    {{- if $text -}}
+      {{- $text = printf "%s.%s" $text $mem -}}
+    {{- else -}}
+      {{- $text = $mem -}}
+    {{- end -}}
     {{- $link = printf "%s#%s" $link $mem -}}
     {{- if .Get 2 -}}
         {{- $text = .Get 2 -}}

ecs/relation.go

@@ -25,16 +25,57 @@ type relationID struct {
 // Relation is the common type for specifying relationship targets.
 // It can be created with [Rel], [RelIdx] and [RelID].
 //
-//   - [Rel] is safe, but has some run-time overhead for component [ID] lookup.
-//   - [RelIdx] is fast but more error-prone.
-//   - [RelID] is used in the [Unsafe] API.
+//   - [Rel] uses a generic type parameter to identify the component.
+//     It is safe, but has some run-time overhead for component [ID] lookup on first usage.
+//   - [RelIdx] uses an index to identify the component. It is fast but more error-prone.
+//   - [RelID] uses a component ID. It is for use with the [Unsafe] API.
 type Relation struct {
 	componentType reflect.Type // Component type of the relation
 	target        Entity       // Target entity of the relation
 	component     ID           // Component ID of the relation
 	index         uint8        // Component index of the relation in a mapper or query
 }
 
+// Rel creates a new [Relation] for a component type.
+//
+// It can be used as a safer but slower alternative to [RelIdx].
+// Requires a component ID lookup when used the first time.
+// On reuse, it is as fast as [RelIdx].
+func Rel[C any](target Entity) Relation {
+	return Relation{
+		target:        target,
+		componentType: reflect.TypeFor[C](),
+		index:         255,
+	}
+}
+
+// RelIdx creates a new [Relation] for a component index.
+// The index refers to the position of the component in the generics
+// of e.g. a [Map2] or [Filter2].
+// For filters, components specified by [Filter2.With] are also covered by the index.
+//
+// It can be used as faster but less safe alternative to [Rel].
+//
+// Note that the index should not be confused with a component [ID] as obtained by [ComponentID]!
+// For component IDs, use [RelID].
+func RelIdx(index int, target Entity) Relation {
+	return Relation{
+		index:  uint8(index),
+		target: target,
+	}
+}
+
+// RelID creates a new [Relation] for a component ID.
+//
+// It is used in Ark's unsafe, ID-based API.
+func RelID(id ID, target Entity) Relation {
+	return Relation{
+		target:    target,
+		component: id,
+		index:     255,
+	}
+}
+
 // relationIDForUnsafe converts the Relation to a relationID.
 //
 // Relation must use ID or component type.
@@ -55,7 +96,7 @@ func (r *Relation) relationIDForUnsafe(world *World) relationID {
 	}
 }
 
-// id returns the component ID of this RelationID.
+// id returns the component ID of this Relation.
 func (r *Relation) id(ids []ID, world *World) ID {
 	if r.index < 255 {
 		return ids[r.index]
@@ -67,50 +108,11 @@ func (r *Relation) id(ids []ID, world *World) ID {
 	return r.component
 }
 
-// targetEntity returns the target [Entity] of this RelationID.
+// targetEntity returns the target [Entity] of this Relation.
 func (r *Relation) targetEntity() Entity {
 	return r.target
 }
 
-// RelID creates a new [Relation] for a component ID.
-//
-// It is used in Ark's unsafe, ID-based API.
-func RelID(id ID, target Entity) Relation {
-	return Relation{
-		target:    target,
-		component: id,
-		index:     255,
-	}
-}
-
-// Rel creates a new [Relation] for a component type.
-//
-// It can be used as a safer but slower alternative to [RelIdx].
-// Required a component ID lookup when used the first time.
-// Un reuse, it is as fast as [RelIdx].
-func Rel[C any](target Entity) Relation {
-	return Relation{
-		target:        target,
-		componentType: reflect.TypeFor[C](),
-		index:         255,
-	}
-}
-
-// RelIdx creates a new [Relation] for a component index.
-//
-// It can be used as faster but less safe alternative to [Rel].
-//
-// Note that the index refers to the position of the component in the generics
-// of e.g. a [Map2] or [Filter2].
-// This should not be confused with component [ID] as obtained by [ComponentID]!
-// For component IDs, use [RelationID].
-func RelIdx(index int, target Entity) Relation {
-	return Relation{
-		index:  uint8(index),
-		target: target,
-	}
-}
-
 // Helper for converting relationSlice
 type relationSlice []Relation