MetaData: edit

pages/MetaData.md

@@ -1,9 +1,8 @@
-MetaData is an interface implemented by various reference types implementing persistent string-based key-value stores.
+MetaData is an interface implemented by various reference types implementing persistent string-based key-value stores. The methods documented below are available in all subclasses.
 
-The methods documented below are available in all subclasses.
+[toc]
 
 ## Subclasses
-
 Subclasses tie the key-value store to various objects recognized by Minetest:
 
 * [[ModStorage]] - per mod
@@ -14,7 +13,6 @@ Subclasses tie the key-value store to various objects recognized by Minetest:
 ## Methods
 
 ### Getters
-
 NOTE: No type information is stored for values; values will be coerced to and from string as needed.
 Mods need to know which type they expect in order to call the appropriate getters & setters.
 Do not rely on coercion to work one way or another; never mix different types.
@@ -44,49 +42,41 @@ assert(got_lua[42] ## true and got_lua[true] ## false)
 Applying serialization to numbers provides you with safe number storage;
 you don't have to worry about C(++) type bounds.
 
-#### Arguments
+**Arguments:**
 
 All getters take only a single argument: The key/name.
 
 - `key` - `{type-string}`: the key/name
 
 #### `:contains(key)`
-
 Checks for the existence of a key-value pair.
 
-##### Returns
-
+**Returns:**
 - `has` - `nil`, `true` or `false`: One of:
   - `nil`: Invalid `self`
   - `false`: No key-value pair with the given key exists.
   - `true`: A key-value pair with the given key exists.
 
 #### `:get(key)`
-
 Retrieves the value associated with a key.
 
-##### Returns
-
+**Returns:**
 - `value` - `nil` or `{type-string}`: Either:
   - `nil` if no matching key-value pair exists, or
   - `{type-string}`: The associated value
 
 #### `:get_string(key)`
-
 Retrieves the value associated with a key & coerces to string.
 
-##### Returns
-
+**Returns:**
 - `value` - `{type-string}`: Either:
   - `""` if no matching key-value pair exists, or
   - `{type-string}`: The associated value
 
 #### `:get_int(key)`
-
 Retrieves the value associated with a key & coerces it to an integer.
 
-##### Returns
-
+**Returns:**
 - `value` - `{type-number}`: Either:
   - `0` if no matching key-value pair exists, or
   - `{type-number}`: The associated value, coerced to an integer
@@ -95,15 +85,14 @@ Retrieves the value associated with a key & coerces it to an integer.
 
 Retrieves the value associated with a key & coerces it to a floating-point number.
 
-##### Returns
-
+**Returns:**
 - `value` - `{type-number}`: Either:
   - `0` if no matching key-value pair exists, or
   - `{type-number}`: The associated value, coerced to a floating point number
 
 ### Setters
 
-#### Arguments & Returns
+**Arguments & Returns:**
 
 Setters have no return values; they all take exactly two arguments: Key & value.
 
@@ -111,17 +100,13 @@ Setters have no return values; they all take exactly two arguments: Key & value.
 - `value` - depends on the setter: the value
 
 #### `:set_string(key, value)`
-
-#### Arguments
-
+**Arguments:**
 - `value` - `{type-string}`: The value to associate with `key`. Either:
   - `""` to remove the key-value pair, or
   - any other string to update/insert a key-value pair
 
 #### `:set_int(key, value)`
-
-#### Arguments
-
+**Arguments:**
 - `value` - `{type-number}`: The integer value to coerce to a string & associate with `key`
 
 WARNING: Integer refers to a C(++) `int` as internally used by the implementation - usually 32 bits wide -
@@ -130,9 +115,7 @@ Be careful when storing integers with large absolute values; they may overflow.
 Keep `value` between `-2^31` and `2^31 - 1`, both inclusive.
 
 #### `:set_float(key, value)`
-
-#### Arguments
-
+**Arguments:**
 - `value` - `{type-number}`: The floating-point value to coerce to a string & associate with `key`
 
 WARNING: The implementation internally uses the C(++) `float` type - usually 32 bits wide -
@@ -140,21 +123,16 @@ whereas Lua guarantees 64-bit "double-precision" floating point numbers.
 This may lead to a precision loss. Large numbers in particular may be hardly representable.
 
 #### `:equals(other)`
-
-##### Arguments
-
+**Arguments:**
 - `other` - MetaData: a MetaData object
 
-##### Returns
-
+**Returns:**
 - `same` - `{type-bool}`: whether `self` has the same key-value pairs as `other`
 
 #### `:to_table()`
-
 Converts the metadata to a Lua table representation.
 
-##### Returns
-
+**Returns:**
 - `value` - `nil` or `{type-table}`: Either:
   - `nil` if the metadata is invalid (?), or
   - `{type-table}`: A table representation of the metadata with the following fields:
@@ -164,17 +142,14 @@ Converts the metadata to a Lua table representation.
 TIP: Use `table = assert(meta:to_table())` to error if the operation failed.
 
 #### `:from_table(table)`
-
 Sets the key-value pairs to match those of a given table representation or clears the metadata.
 
-##### Arguments
-
+**Arguments:**
 - `table` - `{type-table}`: Either:
   - The table representation as produced by `:to_table()`, or
   - Any non-table value: Clears the metadata
 
-##### Returns
-
+**Returns:**
 - `value` - `{type-bool}`: whether loading the table representation succeeded
 
 TIP: Use `assert(meta:from_table(table))` to error if the operation failed.