From e9486838e104a1ad84e790b4980aa9352e5c0620 Mon Sep 17 00:00:00 2001
From: Oleg Jukovec <oleg.jukovec@tarantool.org>
Date: Thu, 4 Aug 2022 15:21:49 +0300
Subject: [PATCH] doc: fix markdown for the decimal subpackage

The patch hides the implementation details of the Decimal type from
documentation. It provides comments for Decimal.MarshalMsgpack and
Decimal.UnmarshalMsgpack.

Closes #201
---
 CHANGELOG.md       |  2 ++
 decimal/bcd.go     | 11 ++++++-----
 decimal/decimal.go | 19 +++++++++++--------
 3 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4b57c82c..6185dc883 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,8 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release.
 
 ### Fixed
 
+- Markdown of documentation for the decimal subpackage (#201)
+
 ## [1.7.0] - 2022-08-02
 
 ### Added
diff --git a/decimal/bcd.go b/decimal/bcd.go
index cf95ccf7c..2cdecb5f0 100644
--- a/decimal/bcd.go
+++ b/decimal/bcd.go
@@ -1,3 +1,5 @@
+package decimal
+
 // Package decimal implements methods to encode and decode BCD.
 //
 // BCD (Binary-Coded Decimal) is a sequence of bytes representing decimal
@@ -26,21 +28,20 @@
 //
 // The decimal -12.34 will be encoded as 0xd6, 0x01, 0x02, 0x01, 0x23, 0x4d:
 //
-// | MP_EXT (fixext 4) | MP_DECIMAL | scale |  1   |  2,3 |  4 (minus) |
-// |        0xd6       |    0x01    | 0x02  | 0x01 | 0x23 | 0x4d       |
+//  | MP_EXT (fixext 4) | MP_DECIMAL | scale |  1   |  2,3 |  4 (minus) |
+//  |        0xd6       |    0x01    | 0x02  | 0x01 | 0x23 | 0x4d       |
 //
 // The decimal 0.000000000000000000000000000000000010 will be encoded as
 // 0xc7, 0x03, 0x01, 0x24, 0x01, 0x0c:
 //
-// | MP_EXT (ext 8) | length | MP_DECIMAL | scale |  1   | 0 (plus) |
-// |      0xc7      |  0x03  |    0x01    | 0x24  | 0x01 | 0x0c     |
+//  | MP_EXT (ext 8) | length | MP_DECIMAL | scale |  1   | 0 (plus) |
+//  |      0xc7      |  0x03  |    0x01    | 0x24  | 0x01 | 0x0c     |
 //
 // See also:
 //
 // * MessagePack extensions https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/
 //
 // * An implementation in C language https://github.com/tarantool/decNumber/blob/master/decPacked.c
-package decimal
 
 import (
 	"fmt"
diff --git a/decimal/decimal.go b/decimal/decimal.go
index b92391ac2..44e192efc 100644
--- a/decimal/decimal.go
+++ b/decimal/decimal.go
@@ -55,6 +55,7 @@ func NewDecimalFromString(src string) (result *Decimal, err error) {
 	return
 }
 
+// MarshalMsgpack serializes the Decimal into a MessagePack representation.
 func (decNum *Decimal) MarshalMsgpack() ([]byte, error) {
 	one := decimal.NewFromInt(1)
 	maxSupportedDecimal := decimal.New(1, DecimalPrecision).Sub(one) // 10^DecimalPrecision - 1
@@ -74,15 +75,17 @@ func (decNum *Decimal) MarshalMsgpack() ([]byte, error) {
 	return bcdBuf, nil
 }
 
-// Decimal values can be encoded to fixext MessagePack, where buffer
-// has a fixed length encoded by first byte, and ext MessagePack, where
-// buffer length is not fixed and encoded by a number in a separate
-// field:
-//
-// +--------+-------------------+------------+===============+
-// | MP_EXT | length (optional) | MP_DECIMAL | PackedDecimal |
-// +--------+-------------------+------------+===============+
+// UnmarshalMsgpack deserializes a Decimal value from a MessagePack
+// representation.
 func (decNum *Decimal) UnmarshalMsgpack(b []byte) error {
+	// Decimal values can be encoded to fixext MessagePack, where buffer
+	// has a fixed length encoded by first byte, and ext MessagePack, where
+	// buffer length is not fixed and encoded by a number in a separate
+	// field:
+	//
+	//  +--------+-------------------+------------+===============+
+	//  | MP_EXT | length (optional) | MP_DECIMAL | PackedDecimal |
+	//  +--------+-------------------+------------+===============+
 	digits, err := decodeStringFromBCD(b)
 	if err != nil {
 		return fmt.Errorf("msgpack: can't decode string from BCD buffer (%x): %w", b, err)