mirror of
https://github.com/minetest/minetest_docs.git
synced 2024-10-04 00:43:07 +02:00
New format, various fixes
This commit is contained in:
parent
b80c70ffc6
commit
775203d8de
51
HOWTO.adoc
51
HOWTO.adoc
@ -34,7 +34,7 @@ local emin, emax = vm:read_from_map(p1, p2) -- Emerged minimum and maximum posit
|
|||||||
|
|
||||||
=== Grammar and Punctuation
|
=== Grammar and Punctuation
|
||||||
* Always capitalize proper names and first letters in plain text.
|
* Always capitalize proper names and first letters in plain text.
|
||||||
** Capitalization in quotation marks is not required and usually discouraged. The goal of quotation in documentation is to mirror _exactly_.
|
** Capitalization in quotation marks is not required and usually discouraged. The goal of quotation in documentation is to mirror _exactly_.
|
||||||
* End all plain text with a period. This does not apply to code examples.
|
* End all plain text with a period. This does not apply to code examples.
|
||||||
* Use the Oxford (or serial) comma. It helps reduce confusion.
|
* Use the Oxford (or serial) comma. It helps reduce confusion.
|
||||||
|
|
||||||
@ -70,17 +70,54 @@ This applies to meta implementations as well. For example, given the constructor
|
|||||||
== Format
|
== Format
|
||||||
See link:templates/standard.adoc[standard template] for an example.
|
See link:templates/standard.adoc[standard template] for an example.
|
||||||
|
|
||||||
|
=== Includes
|
||||||
|
* `config.adoc`: Global doc configuration.
|
||||||
|
* `types.adoc`: Lua types formatted as `type-name` linked to the Lua PIL. Example: `{type-string}`. +
|
||||||
|
All types should link somewhere at some point (cross-reference or outside).
|
||||||
|
|
||||||
=== Functions
|
=== Functions
|
||||||
----
|
----
|
||||||
=== `function_name(parameter_name: type) -> return_types`
|
=== function_name
|
||||||
* `parameter_name`: Description.
|
Description of the function.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
return_values = function_name(argument1, argument2)
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `argument1` | `type` | Argument description.
|
||||||
|
| `argument1` | `type` | Argument description.
|
||||||
|
|===
|
||||||
|
|
||||||
Function description (with return description if applicable).
|
OR
|
||||||
|
|
||||||
|
_None_
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `return_name` | `type` | Return value description.
|
||||||
|
|===
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
_None_
|
||||||
|
|
||||||
|
.Example title
|
||||||
|
====
|
||||||
|
[source,lua]
|
||||||
|
----
|
||||||
|
-- Example code
|
||||||
|
----
|
||||||
|
====
|
||||||
----
|
----
|
||||||
|
|
||||||
=== Tables
|
=== Tables
|
||||||
----
|
----
|
||||||
=== `property_name: type`
|
* `property_name:` `type`
|
||||||
|
* `another_property:` `type`
|
||||||
Property description.
|
** A description.
|
||||||
----
|
----
|
||||||
|
4
include/footer.adoc
Normal file
4
include/footer.adoc
Normal file
@ -0,0 +1,4 @@
|
|||||||
|
|
||||||
|
'''
|
||||||
|
|
||||||
|
Made with https://asciidoctor.org/[AsciiDoctor] | Contribute on {url-docs-repo}[GitHub]
|
12
include/types.adoc
Normal file
12
include/types.adoc
Normal file
@ -0,0 +1,12 @@
|
|||||||
|
:url-pil: https://www.lua.org/pil
|
||||||
|
|
||||||
|
:type-nil: {url-pil}/2.1.html[nil]
|
||||||
|
:type-bool: {url-pil}/2.2.html[bool]
|
||||||
|
:type-number: {url-pil}/2.3.html[number]
|
||||||
|
:type-string: {url-pil}/2.4.html[string]
|
||||||
|
:type-table: {url-pil}/2.5.html[table]
|
||||||
|
:type-function: {url-pil}/2.6.html[function]
|
||||||
|
:type-userdata: {url-pil}/2.7.html[userdata]
|
||||||
|
|
||||||
|
// This should probably be macro'd or something
|
||||||
|
:class-vector: link:../doc/classes/vector.adoc[vector]
|
@ -1,5 +1,6 @@
|
|||||||
= `Vehicle`
|
= Vehicle
|
||||||
include::../include/config.adoc[]
|
include::../include/config.adoc[]
|
||||||
|
include::../include/types.adoc[]
|
||||||
:description: The standard style template for documentation.
|
:description: The standard style template for documentation.
|
||||||
:keywords: standard, template
|
:keywords: standard, template
|
||||||
|
|
||||||
@ -7,34 +8,38 @@ This is the standard template of how a good AsciiDoc should be structured.
|
|||||||
This pragraph describes the purpose of the document.
|
This pragraph describes the purpose of the document.
|
||||||
In this example, an imaginary API for a vehicle will be documented.
|
In this example, an imaginary API for a vehicle will be documented.
|
||||||
|
|
||||||
== `Vehicle` Properties
|
== Vehicle Properties
|
||||||
|
|
||||||
=== `make: string`
|
* `Vehicle.make`: `{type-string}`
|
||||||
The make of the vehicle.
|
* `Vehicle.model`: `{type-string}`
|
||||||
|
* `Vehicle.year`: `{type-number}`
|
||||||
|
* `Vehicle.trim`: `{type-string}`
|
||||||
|
* `Vehicle.color`: `ColorSpec`
|
||||||
|
|
||||||
=== `model: string`
|
== Vehicle Methods
|
||||||
The model of the vehicle.
|
=== Vehicle.new
|
||||||
|
Spawns a new instance of a `Vehicle` at a given position and returns the new object.
|
||||||
|
|
||||||
=== `year: number`
|
==== Usage
|
||||||
The year of the vehicle.
|
----
|
||||||
|
vehicle = Vehicle.new(pos, properties)
|
||||||
|
----
|
||||||
|
|
||||||
=== `trim: string`
|
==== Arguments
|
||||||
The trim of the vehicle.
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `pos` | `{class-vector}` | The position at which the vehicle will be spawned.
|
||||||
|
| `properties` | `{type-table}` | A list of <<Vehicle Properties, Vehicle properties>>.
|
||||||
|
|===
|
||||||
|
|
||||||
=== `color: ColorSpec`
|
==== Returns
|
||||||
The color of the vehicle.
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
== `Vehicle` Methods
|
| `vehicle` | `Vehicle` | The created vehicle.
|
||||||
|
|===
|
||||||
=== `vehicle.new(pos: vector, properties: table) -> Vehicle`
|
|
||||||
* `pos`: The position at which the vehicle will be spanwed.
|
|
||||||
* `properties`: A `table` of Vehicle properties (link).
|
|
||||||
|
|
||||||
Creates a new instance of a `Vehicle` at the given position and returns the new object.
|
|
||||||
|
|
||||||
.Creating a Vehicle
|
.Creating a Vehicle
|
||||||
====
|
====
|
||||||
|
|
||||||
[source,lua]
|
[source,lua]
|
||||||
----
|
----
|
||||||
local minivan = vehicle.new(vector.new(35, 2, 36), {
|
local minivan = vehicle.new(vector.new(35, 2, 36), {
|
||||||
@ -45,65 +50,225 @@ local minivan = vehicle.new(vector.new(35, 2, 36), {
|
|||||||
color = "white",
|
color = "white",
|
||||||
})
|
})
|
||||||
----
|
----
|
||||||
|
|
||||||
====
|
====
|
||||||
|
|
||||||
=== `set_properties(properties: table)`
|
=== Vehicle:set_properties
|
||||||
* `properties`: A `table` of Vehicle properties (link).
|
|
||||||
|
|
||||||
Sets the properties of the vehicle.
|
Sets the properties of the vehicle.
|
||||||
|
|
||||||
=== `get_properties() -> table`
|
==== Usage
|
||||||
|
----
|
||||||
|
vehicle:set_properties(properties)
|
||||||
|
----
|
||||||
|
|
||||||
Returns a `table` of Vehicle properties (link).
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `properties` | `{type-table}` | A list of <<Vehicle Properties, Vehicle properties>>.
|
||||||
|
|===
|
||||||
|
|
||||||
=== `set_pos(pos: vector)`
|
==== Returns
|
||||||
* `pos`: Where to place the vehicle.
|
_None_
|
||||||
|
|
||||||
=== `get_pos() -> vector`
|
=== Vehicle:set_properties
|
||||||
|
Gets the properties of the vehicle.
|
||||||
|
|
||||||
Returns the position of the vehicle.
|
==== Usage
|
||||||
|
----
|
||||||
|
vehicle:get_properties()
|
||||||
|
----
|
||||||
|
|
||||||
=== `set_gear(gear: number) -> boolean`
|
==== Arguments
|
||||||
* `gear`: The gear to shift to. Should be one of
|
_None_
|
||||||
** `-1`: Reverse
|
|
||||||
** `0`: Park
|
|
||||||
** `1` - `3`: First - third gear
|
|
||||||
|
|
||||||
Returns `true` upon success, `false` otherwise.
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `properties` | `{type-table}` | A list of <<Vehicle Properties, Vehicle properties>>.
|
||||||
|
|===
|
||||||
|
|
||||||
=== `get_gear() -> number`
|
=== Vehicle:set_pos
|
||||||
|
Instantly moves the vehicle to the given position.
|
||||||
|
|
||||||
Returns the current gear of the vehicle as a number. See `set_gear` for expected values (link).
|
==== Usage
|
||||||
|
----
|
||||||
|
vehicle:set_pos(pos)
|
||||||
|
----
|
||||||
|
|
||||||
== Global `Vehicle` Functions
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `pos` | `{class-vector}` | The position to move the vehicle to.
|
||||||
|
|===
|
||||||
|
|
||||||
=== `gear_to_name(gear: number) -> string`
|
==== Returns
|
||||||
* `gear`: The gear number to convert.
|
_None_
|
||||||
|
|
||||||
Returns the name of the given gear. Expected return values:
|
=== Vehicle:get_pos
|
||||||
|
Gets the current position of the vehicle.
|
||||||
|
|
||||||
* `-1`: `reverse`
|
==== Usage
|
||||||
* `0`: `park`
|
----
|
||||||
* `1`: `first`
|
vehicle:get_pos()
|
||||||
* `2`: `second`
|
----
|
||||||
* `3`: `third`
|
|
||||||
|
|
||||||
=== `is_electric(make: string, model: string, year: number) -> boolean`
|
==== Arguments
|
||||||
* `make`: The make of the vehicle.
|
_None_
|
||||||
* `model`: The model of the vehicle.
|
|
||||||
* `year`: The year of the vehicle.
|
|
||||||
|
|
||||||
Returns `true` if the given vehicle is electric, `false` otherwise.
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `pos` | `{class-vector}` | The current position of the vehicle.
|
||||||
|
|===
|
||||||
|
|
||||||
.Checking an Electric Vehicle
|
=== Vehicle:set_gear
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
success = vehicle:set_gear(gear)
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `gear` | `{type-number}` a| The gear to shift to. Should be one of
|
||||||
|
|
||||||
|
* `-1`: Reverse
|
||||||
|
* `0`: Park
|
||||||
|
* `1` - `3`: First - third gear.
|
||||||
|
|===
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `success` | `{type-bool}` | Whether placement was successful.
|
||||||
|
|===
|
||||||
|
|
||||||
|
=== Vehicle:get_gear
|
||||||
|
Returns the current gear of the vehicle as a number. See <<Vehicle:set_gear>> for expected values.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
gear = vehicle:get_gear()
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
_None_
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `gear` | `{type-number}` | Gear the vehicle is currently in.
|
||||||
|
|===
|
||||||
|
|
||||||
|
=== Vehicle:some_function
|
||||||
|
Does a thing.
|
||||||
|
|
||||||
|
NOTE: This is a note.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
[horizontal]
|
||||||
|
1::
|
||||||
|
+
|
||||||
|
----
|
||||||
|
stuff = Vehicle:some_function(foo)
|
||||||
|
----
|
||||||
|
2::
|
||||||
|
+
|
||||||
|
----
|
||||||
|
different, things = Vehicle:some_function(foo, bar)
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `foo` | `{class-vector}` | Something.
|
||||||
|
| `bar`? | `{class-vector}` | Something else.
|
||||||
|
|===
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
[horizontal]
|
||||||
|
1::
|
||||||
|
+
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `stuff` | `{type-table}` | Some things.
|
||||||
|
|===
|
||||||
|
|
||||||
|
2::
|
||||||
|
+
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `different` | `{type-table}` | Different things.
|
||||||
|
| `things` | `{type-table}` | More stuff.
|
||||||
|
|===
|
||||||
|
|
||||||
|
== Vehicle Helpers
|
||||||
|
|
||||||
|
=== gear_to_name
|
||||||
|
Returns the name of the given gear.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
name = gear_to_name(gear)
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `gear` | `{type-number}` | Gear to convert to name.
|
||||||
|
|===
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `name` | `{type-string}` a| The name of the given gear. Expected values:
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
!===
|
||||||
|
a! `-1` a! `reverse`
|
||||||
|
a! `0` a! `park`
|
||||||
|
a! `1` a! `first`
|
||||||
|
a! `2` a! `second`
|
||||||
|
a! `3` a! `third`
|
||||||
|
!===
|
||||||
|
|===
|
||||||
|
|
||||||
|
=== vehicle_type
|
||||||
|
Determines the vehicle type based on the make and model.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
vtype = vehicle_type(make, model)
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `make` | `{type-string}` | The vehicle make.
|
||||||
|
| `model` | `{type-string}` | The vehicle model.
|
||||||
|
|===
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
|===
|
||||||
|
| `vtype` | `{type-string}` a| The type of vehicle. Will be one of
|
||||||
|
!===
|
||||||
|
! `sedan`
|
||||||
|
! `hatchback`
|
||||||
|
! `minivan`
|
||||||
|
! `suv`
|
||||||
|
! `van`
|
||||||
|
! `truck`
|
||||||
|
!===
|
||||||
|
|===
|
||||||
|
|
||||||
|
.Checking the Vehicle Type
|
||||||
====
|
====
|
||||||
|
|
||||||
[source,lua]
|
[source,lua]
|
||||||
----
|
----
|
||||||
local ev = is_electric("Toyota", "Previa", 1992) -- false
|
if vehicle_type("Toyota", "Previa") == "minivan" then
|
||||||
|
print("It's a minivan!") --> true
|
||||||
|
end
|
||||||
----
|
----
|
||||||
|
|
||||||
====
|
====
|
||||||
|
|
||||||
Made with https://asciidoctor.org/[AsciiDoctor] | Contribute on {url-docs-repo}[GitHub]
|
include::../include/footer.adoc[]
|
||||||
|
Loading…
Reference in New Issue
Block a user