error: update current documentation

[LeonidVas]

I will try to describe what confuses me and what I suggest to improve.
It's look like the old (before 2.4) and new (after 2.4) descriptions have been squashed with out of a synchronization.

Proposed changes:

1. About description of error before 2.4:

• box.error(code, errtext[, errtext ...]) has two description. I propose squash to one.
• about code in case of using box.error () - it would be nice to add information that code will determine the format of the error message.

2. About description of error after 2.4:

• In the old description of creating an error (box.error () and box.error {}) is need to add a way to create CustomError with a link to the detailed description.
• when type is added to the arguments for box.error () and box.error {}, add a detailed description: "What does this mean" (or a link to a detailed description).

3. Add :unpack() example for every type of generated error:

• ClientError:

tarantool> box.error.new(10, "Space"):unpack()
---
- code: 10
  base_type: ClientError
  type: ClientError
  message: Space 'Space' already exists
  trace:
  - file: '[string "return box.error.new(10, "Space"):unpack()"]'
    line: 1
...

tarantool> box.error.new{ code = 10, reason = "Message" }:unpack()
---
- code: 10
  base_type: ClientError
  type: ClientError
  message: Message
  trace:
  - file: '[string "return box.error.new{code = 10, reason = "Mes..."]'
    line: 1

• CustomError

tarantool> box.error.new("MyType", "Message: %s", "msg"):unpack()
---
- code: 0
  base_type: CustomError
  type: MyType
  custom_type: MyType
  message: 'Message: msg'
  trace:
  - file: '[string "return box.error.new("MyType", "Message: %s",..."]'
    line: 1
...

tarantool> box.error.new{ code  =  10, type  =  "MyType", reason = "Message" }:unpack()
---
- code: 10
  base_type: CustomError
  type: MyType
  custom_type: MyType
  message: Message
  trace:
  - file: '[string "return box.error.new{code = 10, type = "MyTyp..."]'
    line: 1
...

4. Add description of error transmission through netbox (before and after 2.4)

• when an error thrown (IPROTO_ERROR is used)

old (all errors will be converted to ClientError):

tarantool> res, err = pcall(con.call, con, 'box.ctl.wait_ro', {0.001})
---
...

tarantool> err:unpack()
---
- type: ClientError
  code: 115
  message: timed out
  trace:
  - file: builtin/box/net_box.lua
    line: 263
...

new (an error will be transmitted as is):

tarantool> ok, err = pcall(con.call, con, 'box.ctl.wait_ro', {0.001})
---
...

tarantool> err:unpack()
---
- errno: 110
  base_type: TimedOut
  type: TimedOut
  message: timed out
  trace:
  - file: /build/tarantool-2.5.2.11/src/lib/core/fiber_cond.c
    line: 108
...

• when an error transmitted as an object, like return box.error.new() (IPROTO OK is used)

tarantool> function test_error() return box.error.new { code = 3 , reason = "Some reason" } end

old (all errors will be converted to string(error message)):

tarantool> err = con:call('test_error')
---
...

tarantool> type(err)
---
- string
...

tarantool> err
---
- Some reason
...

new (the transparent marshaling can be enabled):

tarantool> con.space._session_settings:update('error_marshaling_enabled', {{'=', 2, true}})
---
- ['error_marshaling_enabled', true]
...

tarantool> err = con:call('test_error')
---
...

tarantool> type(err)
---
- cdata
...

tarantool> err:unpack()
---
- code: 3
  base_type: ClientError
  type: ClientError
  message: Some reason
  trace:
  - file: '[C]'
    line: 4294967295
...