mirror of
https://github.com/minetest/minetest_docs.git
synced 2024-08-20 22:14:17 +02:00
Merge pull request #20 from GreenXenith/standardize
meta - standardize format and HOWTO
This commit is contained in:
commit
e967ae4fcc
127
HOWTO.adoc
Normal file
127
HOWTO.adoc
Normal file
@ -0,0 +1,127 @@
|
|||||||
|
= How to Write Good Documentation
|
||||||
|
include::include/config.adoc[]
|
||||||
|
|
||||||
|
This guide will attempt to help you avoid common documentation issues and help you get your point across as clearly as possible.
|
||||||
|
|
||||||
|
== Writing Style
|
||||||
|
|
||||||
|
=== Passive vs. Active Voice
|
||||||
|
When describing a documentation item, use a passive voice.
|
||||||
|
|
||||||
|
> `thing`: Does a lot of stuff.
|
||||||
|
|
||||||
|
When writing a warning, note, or similar, use an active voice. Speak _to_ the reader.
|
||||||
|
|
||||||
|
> Warning: Doing `this` will give you weird results. You should try to do `that` instead.
|
||||||
|
|
||||||
|
=== Abbreviations
|
||||||
|
When writing in _plain English_, **avoid abbreviations**. This also includes things like "&" instead of "and" and "@" instead of "at".
|
||||||
|
|
||||||
|
When writing _code examples_, **label abbreviations sufficiently**, either by self-labeling (match the abbreviation to the value) or with a comment.
|
||||||
|
|
||||||
|
Bad abbreviations:
|
||||||
|
[source,lua]
|
||||||
|
----
|
||||||
|
local a = VoxelManip(p1, p2) -- BAD: "a" is not a good choice for this variable
|
||||||
|
local emin, emax = a:read_from_map(p1, p2) -- BAD: What does the "e" mean?
|
||||||
|
----
|
||||||
|
|
||||||
|
Good abbreviations:
|
||||||
|
[source,lua]
|
||||||
|
----
|
||||||
|
local vm = VoxelManip(p1, p2) -- GOOD: Self-labeled
|
||||||
|
local emin, emax = vm:read_from_map(p1, p2) -- Emerged minimum and maximum positions (GOOD)
|
||||||
|
----
|
||||||
|
|
||||||
|
=== 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_.
|
||||||
|
* End all plain text with a period. This does not apply to code examples.
|
||||||
|
* Use the Oxford (or serial) comma. It helps reduce confusion.
|
||||||
|
|
||||||
|
|
||||||
|
== Technical Detail
|
||||||
|
This is software documentation, so technical explanations are expected. But it is important to know when and how much to explain technical things.
|
||||||
|
|
||||||
|
=== Object Names
|
||||||
|
When referring to an object, use it's full name, the accepted shorthand, or it's highest generic term.
|
||||||
|
|
||||||
|
For example: An `ItemStack` should be referred to as "ItemStack", "stack", or "object", depending on the need. It should _not_ be referred to as "userdata" or "reference". Objects that have metatables should usually _not_ be referred to as "metatable".
|
||||||
|
|
||||||
|
=== Technical Jargon Saturation
|
||||||
|
Avoid too much technical detail for things that are unimportant, implied, or explained soon after.
|
||||||
|
|
||||||
|
BAD:
|
||||||
|
|
||||||
|
> The `ThisObject` metatable provides an OOP-like utility for processing the index mathematics of a `ThatObject`.
|
||||||
|
|
||||||
|
This has way too much implementation detail and unnecessary technical terms.
|
||||||
|
|
||||||
|
GOOD:
|
||||||
|
|
||||||
|
> The `ThisObject` object is a helper for handling `ThatObject` objects.
|
||||||
|
|
||||||
|
All we need to know is that it helps us handle `ThatObject`. What it actually does should be documented afterwards.
|
||||||
|
|
||||||
|
=== Internal Implementations
|
||||||
|
In general, describing internal implementations is unnecessary and confusing. Avoid it unless absolutely essential for understanding something.
|
||||||
|
|
||||||
|
This applies to meta implementations as well. For example, given the constructor `YourObject()`, do not document it as `YourObject.new(self, o)`. When describing the constructor, say "Creates and returns a new `YourObject` ". Do not go into unnecessary detail about what it does under the hood, such as `__index` management.
|
||||||
|
|
||||||
|
== 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).
|
||||||
|
* `footer.adoc`: Footer for every documentation page.
|
||||||
|
|
||||||
|
=== Functions
|
||||||
|
----
|
||||||
|
=== 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.
|
||||||
|
|===
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
_None_
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `return_name` | `type` | Return value description.
|
||||||
|
|===
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
_None_
|
||||||
|
|
||||||
|
.Example title
|
||||||
|
====
|
||||||
|
[source,lua]
|
||||||
|
----
|
||||||
|
-- Example code
|
||||||
|
----
|
||||||
|
====
|
||||||
|
----
|
||||||
|
|
||||||
|
=== Tables
|
||||||
|
----
|
||||||
|
* `property_name:` `type`
|
||||||
|
* `another_property:` `type`
|
||||||
|
** A description.
|
||||||
|
----
|
||||||
|
|
||||||
|
include::include/footer.adoc[]
|
Binary file not shown.
Before Width: | Height: | Size: 316 KiB |
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,48 +1,274 @@
|
|||||||
= Pomegranates
|
= Vehicle
|
||||||
include::../include/config.adoc[]
|
include::../include/config.adoc[]
|
||||||
:description: A sample template for using AsciiDoc.
|
include::../include/types.adoc[]
|
||||||
:keywords: sample
|
:description: The standard style template for documentation.
|
||||||
|
:keywords: standard, template
|
||||||
|
|
||||||
This is a sample template of how a good AsciiDoc can be structured.
|
This is the standard template of how a good AsciiDoc should be structured.
|
||||||
This pragraph describes the purpose of the document.
|
This paragraph describes the purpose of the document.
|
||||||
In this sample, an imaginary API
|
In this example, an imaginary API for a vehicle will be documented.
|
||||||
for producing pomegranates will be documented.
|
|
||||||
|
|
||||||
So without further ado, here is what we should see when we are done.
|
== Vehicle Properties
|
||||||
|
|
||||||
[#img-pomegranate]
|
* `Vehicle.make`: `{type-string}`
|
||||||
.The Expected Result
|
* `Vehicle.model`: `{type-string}`
|
||||||
image::pomegranate.png[Pomegranate]
|
* `Vehicle.year`: `{type-number}`
|
||||||
|
* `Vehicle.trim`: `{type-string}`
|
||||||
|
* `Vehicle.color`: `ColorSpec`
|
||||||
|
|
||||||
== Pomegranate API Methods
|
== Vehicle Methods
|
||||||
|
=== Vehicle.new
|
||||||
|
Spawns a new instance of a `Vehicle` at a given position and returns the new object.
|
||||||
|
|
||||||
=== `plant_tree(pos, name)`
|
==== Usage
|
||||||
* `pos`: `vector`
|
----
|
||||||
* `name`: `string`
|
vehicle = Vehicle.new(pos, properties)
|
||||||
|
----
|
||||||
|
|
||||||
Plants a tree of type `name` at `pos`
|
==== Arguments
|
||||||
if `name` is a registered pomegranate tree.
|
[%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>>.
|
||||||
|
|===
|
||||||
|
|
||||||
.Planting A Tree
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `vehicle` | `Vehicle` | The created vehicle.
|
||||||
|
|===
|
||||||
|
|
||||||
|
.Creating a Vehicle
|
||||||
|
====
|
||||||
|
[source,lua]
|
||||||
|
----
|
||||||
|
local minivan = vehicle.new(vector.new(35, 2, 36), {
|
||||||
|
make = "Toyota",
|
||||||
|
model = "Previa",
|
||||||
|
year = 1992,
|
||||||
|
trim = "LE",
|
||||||
|
color = "white",
|
||||||
|
})
|
||||||
|
----
|
||||||
|
====
|
||||||
|
|
||||||
|
=== Vehicle:set_properties
|
||||||
|
Sets the properties of the vehicle.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
vehicle:set_properties(properties)
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `properties` | `{type-table}` | A list of <<Vehicle Properties, Vehicle properties>>.
|
||||||
|
|===
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
_None_
|
||||||
|
|
||||||
|
=== Vehicle:set_properties
|
||||||
|
Gets the properties of the vehicle.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
vehicle:get_properties()
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
_None_
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `properties` | `{type-table}` | A list of <<Vehicle Properties, Vehicle properties>>.
|
||||||
|
|===
|
||||||
|
|
||||||
|
=== Vehicle:set_pos
|
||||||
|
Instantly moves the vehicle to the given position.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
vehicle:set_pos(pos)
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `pos` | `{class-vector}` | The position to move the vehicle to.
|
||||||
|
|===
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
_None_
|
||||||
|
|
||||||
|
=== Vehicle:get_pos
|
||||||
|
Gets the current position of the vehicle.
|
||||||
|
|
||||||
|
==== Usage
|
||||||
|
----
|
||||||
|
vehicle:get_pos()
|
||||||
|
----
|
||||||
|
|
||||||
|
==== Arguments
|
||||||
|
_None_
|
||||||
|
|
||||||
|
==== Returns
|
||||||
|
[%autowidth, frame=none]
|
||||||
|
|===
|
||||||
|
| `pos` | `{class-vector}` | The current position of the 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]
|
||||||
----
|
----
|
||||||
plant_tree(vector.new(35, 42, 36), "regular")
|
if vehicle_type("Toyota", "Previa") == "minivan" then
|
||||||
|
print("It's a minivan!") --> true
|
||||||
|
end
|
||||||
----
|
----
|
||||||
|
|
||||||
====
|
====
|
||||||
|
|
||||||
=== `grow_tree(pos)`
|
include::../include/footer.adoc[]
|
||||||
* `pos`: `vector`
|
|
||||||
|
|
||||||
Grows the tree at `pos` if the node at `pos` is a valid pomegranate tree.
|
|
||||||
|
|
||||||
=== `spray_tree(pos, pesticide)`
|
|
||||||
* `pos`: `vector`
|
|
||||||
* `pesticide`: `string`
|
|
||||||
|
|
||||||
Sprays tree at `pos` with `pesticide` if it is a registered chemical.
|
|
||||||
|
|
||||||
== Source
|
|
||||||
You can contribute to the documentation at {url-docs-repo}[our GitHub repository]!
|
|
||||||
|
Loading…
Reference in New Issue
Block a user