update docs

gopherd · Sep 28, 2024 · af47d07 · af47d07
1 parent c72a0d6
commit af47d07
Show file tree

Hide file tree

Showing 7 changed files with 172 additions and 12 deletions.
diff --git a/src/compile/generate.go b/src/compile/generate.go
@@ -133,7 +133,12 @@ func Generate(c *Compiler) error {
 	return nil
 }
 
-// @api(Map) represents a language map file. Usually, it is a text file that contains
+// @api(Map)
+//
+//	import Tabs from "@theme/Tabs";
+//	import TabItem from "@theme/TabItem";
+//
+// `Map` represents a language map file. Usually, it is a text file that contains
 // key-value pairs separated by a equal sign. The key is the name of the language feature.
 // The built-in keys are:
 //
@@ -156,8 +161,17 @@ func Generate(c *Compiler) error {
 //   - **map**: the map type for the language
 //   - **box**: the box replacement for the language (for java, e.g., box(int) = Integer)
 //
-// Here is an example of a language map file for the Java language:
+// Here are some examples of language map files:
+//
+//	<Tabs
+//	  defaultValue="java"
+//	  values={[
+//	    { label: 'java.map', value: 'java' },
+//	    { label: 'cpp.map', value: 'cpp' },
+//	    { label: 'protobuf.map', value: 'protobuf' },
+//	  ]}>
 //
+//	<TabItem value="java">
 //	```map title="java.map"
 //	ext=.java
 //	comment=// %T%
@@ -188,10 +202,60 @@ func Generate(c *Compiler) error {
 //	box(double)=Double
 //	box(boolean)=Boolean
 //	```
+//	</TabItem>
+//
+//	<TabItem value="cpp">
+//	```map title="cpp.map"
+//	ext=.h
+//	comment=// %T%
+//
+//	int=int
+//	int8=int8_t
+//	int16=int16_t
+//	int32=int32_t
+//	int64=int64_t
+//	float32=float
+//	float64=double
+//	bool=bool
+//	string=std::string
+//	byte=unsigned char
+//	bytes=std::vector<unsigned char>
+//	any=std::any
+//	map=std::unordered_map<%K%, %V%>
+//	vector=std::vector<%T%>
+//	array=std::array<%T%, %N%>
+//	```
+//	</TabItem>
+//
+//	<TabItem value="protobuf">
+//	```map title="protobuf.map"
+//	ext=.proto
+//	comment=// %T%
+//
+//	int=int32
+//	int8=int32
+//	int16=int32
+//	int32=int32
+//	int64=int64
+//	float32=float
+//	float64=double
+//	bool=bool
+//	string=string
+//	byte=int8
+//	bytes=bytes
+//	any=google.protobuf.Any
+//	map=map<%K%, %V%>
+//	vector=repeated %T.E%
+//	array=repeated %T.E%
+//	```
+//	</TabItem>
+//
+//	</Tabs>
 //
-// :::note
+// :::tip
 //
 // - The `%T%`, `%K%`, `%V%` and `%N%` are placeholders for the type, key type, value type and number of array elements.
+// - `%T.E%` is the final element type of `%T%`. It's useful if you need to get the final element type of a vector or array.
 // - Line comments are started with the `#` character and it must be the first character of the line (leading spaces are allowed).
 //
 //	```plain title="java.map"

diff --git a/src/compile/next.go b/src/compile/next.go
@@ -1,4 +1,4 @@
-//go:generate go run github.com/gopherd/tools/cmd/docgen@v0.0.7 -ext .mdx -I ./ -o ../../website/docs/api/preview -level 0 -M "---" -M "pagination_prev: null" -M "pagination_next: null" -M "---"
+//go:generate go run github.com/gopherd/tools/cmd/docgen@v0.0.8 -ext .mdx -I ./ -o ../../website/docs/api/preview -level 0 -M "---" -M "pagination_prev: null" -M "pagination_next: null" -M "---"
 package compile
 
 import (

diff --git a/src/compile/object.go b/src/compile/object.go
@@ -34,7 +34,15 @@ type Imports[T Decl] struct {
 	//	package a;
 	//	```
 	//
-	//	```npl title="file.npl"
+	//	<Tabs
+	//		defaultValue="file"
+	//	  values={[
+	//	    { label: 'file.npl', value: 'file' },
+	//	    { label: 'package.npl', value: 'package' },
+	//	  ]}>
+	//
+	//	<TabItem value="file">
+	//	```npl
 	//	{{- define "meta/this" -}}file{{- end -}}
 	//
 	//	{{range this.Imports.List}}
@@ -47,8 +55,10 @@ type Imports[T Decl] struct {
 	//	```
 	//	file1
 	//	```
+	//	</TabItem>
 	//
-	//	```npl title="package.npl"
+	//	<TabItem value="package">
+	//	```npl
 	//	{{- define "meta/this" -}}package{{- end -}}
 	//
 	//	{{range this.Imports.List}}
@@ -61,6 +71,9 @@ type Imports[T Decl] struct {
 	//	```
 	//	a
 	//	```
+	//	</TabItem>
+	//
+	//	</Tabs>
 	Decl Node
 
 	// @api(Object/Imports.List) represents a slice of [Import](#Object/Import) declarations: **\[[Import](#Object/Import)\]**.

diff --git a/src/compile/types.go b/src/compile/types.go
@@ -18,7 +18,12 @@ import (
 
 // -------------------------------------------------------------------------
 
-// @api(Object) is a generic object type. These objects can be used as parameters for the `Context/next`
+// @api(Object)
+//
+//	import Tabs from "@theme/Tabs";
+//	import TabItem from "@theme/TabItem";
+//
+// `Object` is a generic object type. These objects can be used as parameters for the `Context/next`
 // function, like `{{next .}}`.
 type Object interface {
 	// @api(Object.Typeof) returns the type name of the object.

diff --git a/src/grammar/grammar.go b/src/grammar/grammar.go
@@ -1,4 +1,4 @@
-//go:generate go run github.com/gopherd/tools/cmd/docgen@v0.0.7 -ext .mdx -I ./ -o ../../website/docs/api/preview -level 0 -M "---" -M "pagination_prev: null" -M "pagination_next: null" -M "---"
+//go:generate go run github.com/gopherd/tools/cmd/docgen@v0.0.8 -ext .mdx -I ./ -o ../../website/docs/api/preview -level 0 -M "---" -M "pagination_prev: null" -M "pagination_next: null" -M "---"
 package grammar
 
 // @api(Grammar) represents the custom grammar for the next files.

diff --git a/website/docs/api/preview/map.mdx b/website/docs/api/preview/map.mdx
@@ -4,6 +4,9 @@ pagination_next: null
 ---
 # Map {#user-content-Map}
 
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 `Map` represents a language map file. Usually, it is a text file that contains key-value pairs separated by a equal sign. The key is the name of the language feature. The built-in keys are:
 
 - **ext**: the file extension for the language
@@ -25,8 +28,17 @@ pagination_next: null
 - **map**: the map type for the language
 - **box**: the box replacement for the language (for java, e.g., box(int) = Integer)
 
-Here is an example of a language map file for the Java language:
+Here are some examples of language map files:
+
+<Tabs
+  defaultValue="java"
+  values={[
+    { label: 'java.map', value: 'java' },
+    { label: 'cpp.map', value: 'cpp' },
+    { label: 'protobuf.map', value: 'protobuf' },
+  ]}>
 
+<TabItem value="java">
 ```map title="java.map"
 ext=.java
 comment=// %T%
@@ -57,10 +69,60 @@ box(float)=Float
 box(double)=Double
 box(boolean)=Boolean
 ```
+</TabItem>
+
+<TabItem value="cpp">
+```map title="cpp.map"
+ext=.h
+comment=// %T%
+
+int=int
+int8=int8_t
+int16=int16_t
+int32=int32_t
+int64=int64_t
+float32=float
+float64=double
+bool=bool
+string=std::string
+byte=unsigned char
+bytes=std::vector<unsigned char>
+any=std::any
+map=std::unordered_map<%K%, %V%>
+vector=std::vector<%T%>
+array=std::array<%T%, %N%>
+```
+</TabItem>
+
+<TabItem value="protobuf">
+```map title="protobuf.map"
+ext=.proto
+comment=// %T%
+
+int=int32
+int8=int32
+int16=int32
+int32=int32
+int64=int64
+float32=float
+float64=double
+bool=bool
+string=string
+byte=int8
+bytes=bytes
+any=google.protobuf.Any
+map=map<%K%, %V%>
+vector=repeated %T.E%
+array=repeated %T.E%
+```
+</TabItem>
+
+</Tabs>
 
-:::note
+:::tip
 
 - The `%T%`, `%K%`, `%V%` and `%N%` are placeholders for the type, key type, value type and number of array elements.
+- `%T.E%` is the final element type of `%T%`. It's useful if you need to get the final element type of a vector or array.
 - Line comments are started with the `#` character and it must be the first character of the line (leading spaces are allowed).
 
 ```plain title="java.map"

diff --git a/website/docs/api/preview/object.mdx b/website/docs/api/preview/object.mdx
@@ -4,6 +4,9 @@ pagination_next: null
 ---
 # Object {#user-content-Object}
 
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 `Object` is a generic object type. These objects can be used as parameters for the `Context/next` function, like `{{next .}}`.
 
 ###### .Typeof {#user-content-Object__Typeof}
@@ -1717,7 +1720,15 @@ import "path/to/file2.next";
 package a;
 ```
 
-```npl title="file.npl"
+<Tabs
+	defaultValue="file"
+  values={[
+    { label: 'file.npl', value: 'file' },
+    { label: 'package.npl', value: 'package' },
+  ]}>
+
+<TabItem value="file">
+```npl
 {{- define "meta/this" -}}file{{- end -}}
 
 {{range this.Imports.List}}
@@ -1730,8 +1741,10 @@ Output (for file1.next):
 ```
 file1
 ```
+</TabItem>
 
-```npl title="package.npl"
+<TabItem value="package">
+```npl
 {{- define "meta/this" -}}package{{- end -}}
 
 {{range this.Imports.List}}
@@ -1744,6 +1757,9 @@ Output:
 ```
 a
 ```
+</TabItem>
+
+</Tabs>
 
 </div>