Clearify docs for ExternalResource and RemoteFile (#1248)

* Update code docs for ExternalResource emphasising its properties

* Update code docs for ExternalResource emphasising its representative file location

* Update mirai-core-api/src/commonMain/kotlin/utils/RemoteFile.kt

* Update mirai-core-api/src/commonMain/kotlin/utils/RemoteFile.kt

* Clarify docs

mirai-core-api/src/commonMain/kotlin/utils/ExternalResource.kt

@@ -36,7 +36,7 @@ import java.io.*
 
 
 /**
- * 一个*不可变的*外部资源.
+ * 一个*不可变的*外部资源. 仅包含资源内容, 大小, 文件类型, 校验值而不包含文件名, 文件位置等. 外部资源有可能是一个文件, 也有可能只存在于内存, 或者以任意其他方式实现.
  *
  * [ExternalResource] 在创建之后就应该保持其属性的不变, 即任何时候获取其属性都应该得到相同结果, 任何时候打开流都得到的一样的数据.
  *
@@ -51,6 +51,12 @@ import java.io.*
  * 当 [ExternalResource] 创建时就可能会打开一个文件 (如使用 [File.toExternalResource]).
  * 类似于 [InputStream], [ExternalResource] 需要被 [关闭][close].
  *
+ * ## 实现 [ExternalResource]
+ *
+ * 可以自行实现 [ExternalResource]. 但通常上述创建方法已足够使用.
+ *
+ * 实现时需保持 [ExternalResource] 在构造后就不可变, 并且所有属性都总是返回一个固定值.
+ *
  * @see ExternalResource.uploadAsImage 将资源作为图片上传, 得到 [Image]
  * @see ExternalResource.sendAsImageTo 将资源作为图片发送
  * @see Contact.uploadImage 上传一个资源作为图片, 得到 [Image]
@@ -72,6 +78,9 @@ public interface ExternalResource : Closeable {
     public val sha1: ByteArray
         get() =
             throw UnsupportedOperationException("ExternalResource.sha1 is not implemented by ${this::class.simpleName}")
+    // 如果你要实现 [ExternalResource], 你也应该实现 [sha1].
+    // 这里默认抛出 [UnsupportedOperationException] 是为了 (姑且) 兼容 2.5 以前的版本的实现.
+
 
     /**
      * 文件格式，如 "png", "amr". 当无法自动识别格式时为 [DEFAULT_FORMAT_NAME].

mirai-core-api/src/commonMain/kotlin/utils/RemoteFile.kt

@@ -270,6 +270,15 @@ public interface RemoteFile {
      *
      * [moveTo] 只会操作远程文件, 而不会修改当前 [RemoteFile.path].
      *
+     * **注意**: 与 [java.io.File] 类似, 这是将当前 [RemoteFile] 移动到作为 [target], 而不是移动成为 [target] 的子文件或目录. 例如:
+     * ```
+     * val root = group.filesRoot
+     * root.resolve("test.txt").moveTo(root) // 错误! 这是在将该文件的路径 "test.txt" 修改为 “/” , 而不是修改为 "/test.txt"
+     * root.resolve("test.txt").moveTo(root.resolve("/")) // 错误! 与上一行相同.
+
+     * root.resolve("/test.txt").moveTo(root.resolve("/test2.txt")) // 正确. 将该文件的路径 "/test.txt" 修改为 “/test2.txt”，相当于重命名文件
+     * ```
+     *
      * @param target 目标文件位置.
      */
     public suspend fun moveTo(target: RemoteFile): Boolean
@@ -420,6 +429,18 @@ public interface RemoteFile {
      *
      * 相关问题: [#1250: 群文件在上传后 toRemoteFile 返回 null](https://github.com/mamoe/mirai/issues/1250)
      *
+     *
+     * **注意**: [resource] 仅表示资源数据, 而不带有文件名属性.
+     * 与 [java.io.File] 类似, [upload] 是将 [resource] 上传成为 [this][RemoteFile], 而不是上传成为 [this][RemoteFile] 的子文件. 示例:
+     * ```
+     * group.filesRoot.upload(resource) // 错误! 这是在把资源上传成为根目录.
+     * group.filesRoot.resolve("/").upload(resource) // 错误! 与上一句相同, 这是在把资源上传成为根目录.
+     *
+     * val root = group.filesRoot
+     * root.resolve("test.txt").upload(resource) // 正确. 把资源上传成为根目录下的 "test.txt".
+     * root.resolve("/test.txt").upload(resource) // 正确. 与上一句相同, 把资源上传成为根目录下的 "test.txt".
+     * ```
+     *
      * @param resource 需要上传的文件资源. 无论上传是否成功, 本函数都不会关闭 [resource].
      * @param callback 进度回调
      * @throws IllegalStateException 该文件上传失败或权限不足时抛出