[Docs] Update Japanese translation of i2c_driver.md (#8523)

* Update Japanese translation of i2c_driver.md

* Apply a part of suggestions from code review

1 files changed, 34 insertions, 24 deletions

diff --git a/docs/ja/i2c_driver.md b/docs/ja/i2c_driver.md
index 4030da631a..56425a2fdb 100644
--- a/docs/ja/i2c_driver.md
+++ b/docs/ja/i2c_driver.md
@@ -1,38 +1,48 @@
-# I2C マスタドライバ
+# I2C マスタドライバ :id=i2c-master-driver
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: 85041ff05:docs/i2c_driver.md
-  git diff 85041ff05 HEAD -- docs/i2c_driver.md | cat
+  original document: 0.8.62:docs/i2c_driver.md
+  git diff 0.8.62 HEAD -- docs/i2c_driver.md | cat
 -->
 
 QMK で使われる I2C マスタドライバには、MCU 間のポータビリティを提供するための一連の関数が用意されています。
 
-## 使用できる関数
+## I2C アドレスについての重要なメモ :id=note-on-i2c-addresses
+
+このドライバが期待する全てのアドレスは、アドレスバイトの上位7ビットにプッシュする必要があります。最下位ビットの設定(読み込み/書き込みを示す)は、それぞれの関数によって行われます。データシートやインターネットで列挙されているほとんど全ての I2C アドレスは、下位7ビットを占める7ビットとして表され、1ビット左(より上位)にシフトする必要があります。これは、ビット単位のシフト演算子 `<< 1` を使用して簡単に実行できます。
+
+これは、呼び出しごとに以下の関数を実行するか、アドレスの定義で1度だけ実行するかどちらかで行うことができます。例えば、デバイスのアドレスが `0x18` の場合:
+
+`#define MY_I2C_ADDRESS (0x18 << 1)`
+
+I2C アドレスと他の技術詳細について、さらなる情報を得るためには https://www.robot-electronics.co.uk/i2c-tutorial を見てください。
+
+## 使用できる関数 :id=available-functions
 
 | 関数                                                                                                        | 説明                                                                                                                                                                                |
 |-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `void i2c_init(void);`                                                                                      | I2C ドライバを初期化します。他のあらゆるトランザクションを開始する前に、この関数を一度だけ呼ぶ必要があります。                                                                      |
-| `uint8_t i2c_start(uint8_t address, uint16_t timeout);`                                                     | I2C トランザクションを開始します。アドレスは方向ビットのない7ビットスレーブアドレスです。                                                                                           |
-| `uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                  | I2C 経由でデータを送信します。アドレスは方向ビットのない7ビットスレーブアドレスです。トランザクションのステータスを返します。                                                       |
-| `uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                   | I2C 経由でデータを受信します。アドレスは方向ビットのない7ビットスレーブアドレスです。 `length` で指定した長さのバイト列を `data` に保存し、トランザクションのステータスを返します。 |
-| `uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` | `i2c_transmit` と同様ですが、 `regaddr` でスレーブのデータ書き込み先のレジスタを指定します。                                                                                    |
-| `uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`  | `i2c_receive` と同様ですが、 `regaddr` でスレーブのデータ読み込み先のレジスタを指定します。                                                                                     |
-| `uint8_t i2c_stop(void);`                                                                                   | I2C トランザクションを終了します。                                                                                                                                                  |
+| `i2c_status_t i2c_start(uint8_t address, uint16_t timeout);`                                                     | I2C トランザクションを開始します。アドレスは方向ビットのない7ビットスレーブアドレスです。                                                                                           |
+| `i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                  | I2C 経由でデータを送信します。アドレスは方向ビットのない7ビットスレーブアドレスです。トランザクションのステータスを返します。                                                       |
+| `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);`                   | I2C 経由でデータを受信します。アドレスは方向ビットのない7ビットスレーブアドレスです。 `length` で指定した長さのバイト列を `data` に保存し、トランザクションのステータスを返します。 |
+| `i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` | `i2c_transmit` と同様ですが、 `regaddr` でスレーブのデータ書き込み先のレジスタを指定します。                                                                                    |
+| `i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);`  | `i2c_receive` と同様ですが、 `regaddr` でスレーブのデータ読み込み先のレジスタを指定します。                                                                                     |
+| `i2c_status_t i2c_stop(void);`                                                                                   | I2C トランザクションを終了します。                                                                                                                                                  |
 
-### 関数の戻り値
+### 関数の戻り値 :id=function-return
 
 `void i2c_init(void)` を除く上にあるすべての関数は、次の真理値表にある値を返します。
 
-| 戻り値 | 説明                         |
-|--------|------------------------------|
-| 0      | 処理が正常に実行されました。 |
-| -1     | 処理に失敗しました。         |
-| -2     | 処理がタイムアウトしました。 |
+|戻り値の定数        |値 |説明                        |
+|--------------------|---|----------------------------|
+|`I2C_STATUS_SUCCESS`|0  |処理が正常に実行されました。|
+|`I2C_STATUS_ERROR`  |-1 |処理に失敗しました。        |
+|`I2C_STATUS_TIMEOUT`|-2 |処理がタイムアウトしました。|
 
-## AVR
+## AVR :id=avr
 
-### 設定
+### 設定 :id=avr-configuration
 
 I2Cマスタドライバを設定するために、次の定義が使えます。
 
@@ -43,11 +53,11 @@ I2Cマスタドライバを設定するために、次の定義が使えます�
 
 AVR は通常 I2C ピンとして使う GPIO が設定されているので、これ以上の設定は必要ありません。
 
-## ARM
+## ARM :id=arm
 
 ARM の場合は、内部に ChibiOS I2C HAL ドライバがあります。この節では STM32 MCU を使用していると仮定します。
 
-### 設定
+### 設定 :id=arm-configuration
 
 ARM MCU 用の設定はしばしば非常に複雑です。これは、多くの場合複数の I2C ドライバをさまざまなポートに対して割り当てられるためです。
 
@@ -82,7 +92,7 @@ ChibiOS I2C ドライバの設定項目は STM32 MCU の種類に依存します
     STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx, STM32L1xx では I2Cv1 が使われます。
     STM32F0xx, STM32F3xx, STM32F7xx, STM32L4xx では I2Cv2 が使われます。
 
-#### I2Cv1
+#### I2Cv1 :id=i2cv1
 
 STM32 MCU の I2Cv1 では、クロック周波数とデューティ比を次の変数で変更できます。詳しくは <https://www.playembedded.org/blog/stm32-i2c-chibios/#I2Cv1_configuration_structure> を参照してください。
 
@@ -92,7 +102,7 @@ STM32 MCU の I2Cv1 では、クロック周波数とデューティ比を次の
 | `I2C1_CLOCK_SPEED` | `100000`         |
 | `I2C1_DUTY_CYCLE`  | `STD_DUTY_CYCLE` |
 
-#### I2Cv2
+#### I2Cv2 :id=i2cv2
 
 STM32 MCU の I2Cv2 では、信号のタイミングパラメータを次の変数で変更できます。詳しくは <https://www.st.com/en/embedded-software/stsw-stm32126.html> を参照してください。
 
@@ -111,11 +121,11 @@ STM32 MCU では GPIO ピンを設定するとき、別の「代替機能」モ�
 | `I2C1_SCL_PAL_MODE` | `4`    |
 | `I2C1_SDA_PAL_MODE` | `4`    |
 
-#### その他
+#### その他 :id=other
 
 `void i2c_init(void)` 関数は `weak` 属性が付いており、オーバーロードすることができます。この場合、上記で設定した変数は使用されません。可能な GPIO の設定については、 MCU のデータシートを参照してください。次に示すのは初期化関数の例です：
 
-```C
+```c
 void i2c_init(void)
 {
   setPinInput(B6); // Try releasing special pins for a short time