mirror of
https://github.com/minetest/minetest_docs.git
synced 2024-07-04 15:15:15 +02:00
New format, various fixes
This commit is contained in:
GreenXenith
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
|
||||
* 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.
|
||||
* 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
|
||||
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
|
||||
----
|
||||
=== `function_name(parameter_name: type) -> return_types`
|
||||
* `parameter_name`: Description.
|
||||
=== function_name
|
||||
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
|
||||
----
|
||||
=== `property_name: type`
|
||||
|
||||
Property description.
|
||||
* `property_name:` `type`
|
||||
* `another_property:` `type`
|
||||
** 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/types.adoc[]
|
||||
:description: The standard style template for documentation.
|
||||
: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.
|
||||
In this example, an imaginary API for a vehicle will be documented.
|
||||
|
||||
== `Vehicle` Properties
|
||||
== Vehicle Properties
|
||||
|
||||
=== `make: string`
|
||||
The make of the vehicle.
|
||||
* `Vehicle.make`: `{type-string}`
|
||||
* `Vehicle.model`: `{type-string}`
|
||||
* `Vehicle.year`: `{type-number}`
|
||||
* `Vehicle.trim`: `{type-string}`
|
||||
* `Vehicle.color`: `ColorSpec`
|
||||
|
||||
=== `model: string`
|
||||
The model of the vehicle.
|
||||
== Vehicle Methods
|
||||
=== Vehicle.new
|
||||
Spawns a new instance of a `Vehicle` at a given position and returns the new object.
|
||||
|
||||
=== `year: number`
|
||||
The year of the vehicle.
|
||||
==== Usage
|
||||
----
|
||||
vehicle = Vehicle.new(pos, properties)
|
||||
----
|
||||
|
||||
=== `trim: string`
|
||||
The trim of the vehicle.
|
||||
==== Arguments
|
||||
[%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`
|
||||
The color of the vehicle.
|
||||
|
||||
== `Vehicle` Methods
|
||||
|
||||
=== `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.
|
||||
==== Returns
|
||||
[%autowidth, frame=none]
|
||||
|===
|
||||
| `vehicle` | `Vehicle` | The created vehicle.
|
||||
|===
|
||||
|
||||
.Creating a Vehicle
|
||||
====
|
||||
|
||||
[source,lua]
|
||||
----
|
||||
local minivan = vehicle.new(vector.new(35, 2, 36), {
|
||||
@ -45,65 +50,225 @@ local minivan = vehicle.new(vector.new(35, 2, 36), {
|
||||
color = "white",
|
||||
})
|
||||
----
|
||||
|
||||
====
|
||||
|
||||
=== `set_properties(properties: table)`
|
||||
* `properties`: A `table` of Vehicle properties (link).
|
||||
|
||||
=== Vehicle:set_properties
|
||||
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)`
|
||||
* `pos`: Where to place the vehicle.
|
||||
==== Returns
|
||||
_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`
|
||||
* `gear`: The gear to shift to. Should be one of
|
||||
** `-1`: Reverse
|
||||
** `0`: Park
|
||||
** `1` - `3`: First - third gear
|
||||
==== Arguments
|
||||
_None_
|
||||
|
||||
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`
|
||||
* `gear`: The gear number to convert.
|
||||
==== Returns
|
||||
_None_
|
||||
|
||||
Returns the name of the given gear. Expected return values:
|
||||
=== Vehicle:get_pos
|
||||
Gets the current position of the vehicle.
|
||||
|
||||
* `-1`: `reverse`
|
||||
* `0`: `park`
|
||||
* `1`: `first`
|
||||
* `2`: `second`
|
||||
* `3`: `third`
|
||||
==== Usage
|
||||
----
|
||||
vehicle:get_pos()
|
||||
----
|
||||
|
||||
=== `is_electric(make: string, model: string, year: number) -> boolean`
|
||||
* `make`: The make of the vehicle.
|
||||
* `model`: The model of the vehicle.
|
||||
* `year`: The year of the vehicle.
|
||||
==== Arguments
|
||||
_None_
|
||||
|
||||
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]
|
||||
----
|
||||
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