mirror of
https://github.com/minetest/minetest_docs.git
synced 2024-07-04 15:15:15 +02:00
Merge pull request #20 from GreenXenith/standardize
meta - standardize format and HOWTO
This commit is contained in:
benrob0329
GitHub
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[]
|
||||
:description: A sample template for using AsciiDoc.
|
||||
:keywords: sample
|
||||
include::../include/types.adoc[]
|
||||
:description: The standard style template for documentation.
|
||||
:keywords: standard, template
|
||||
|
||||
This is a sample template of how a good AsciiDoc can be structured.
|
||||
This pragraph describes the purpose of the document.
|
||||
In this sample, an imaginary API
|
||||
for producing pomegranates will be documented.
|
||||
This is the standard template of how a good AsciiDoc should be structured.
|
||||
This paragraph describes the purpose of the document.
|
||||
In this example, an imaginary API for a vehicle will be documented.
|
||||
|
||||
So without further ado, here is what we should see when we are done.
|
||||
== Vehicle Properties
|
||||
|
||||
[#img-pomegranate]
|
||||
.The Expected Result
|
||||
image::pomegranate.png[Pomegranate]
|
||||
* `Vehicle.make`: `{type-string}`
|
||||
* `Vehicle.model`: `{type-string}`
|
||||
* `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)`
|
||||
* `pos`: `vector`
|
||||
* `name`: `string`
|
||||
==== Usage
|
||||
----
|
||||
vehicle = Vehicle.new(pos, properties)
|
||||
----
|
||||
|
||||
Plants a tree of type `name` at `pos`
|
||||
if `name` is a registered pomegranate tree.
|
||||
==== 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>>.
|
||||
|===
|
||||
|
||||
.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]
|
||||
----
|
||||
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)`
|
||||
* `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]!
|
||||
include::../include/footer.adoc[]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user