WIP

README.ja.md

@@ -593,7 +593,6 @@ CABIが適用されるのは、外部アセンブリから参照可能な場合
 
 メソッドのシグネチャは、メソッドのオーバーロードを特定するために使用されます。
 シグネチャを指定せず、オーバーロードメソッドが複数存在する場合は、誤ったメソッドを選択する可能性があります。
-通常、戻り値の型は検証されませんが、 `op_Implicit` 及び `op_Explicit` メソッドの場合のみ、戻り値の型も一致する事が確認されます。
 
 .NETメソッドを参照するために、コマンドラインオプション `-l` で、メソッド定義を含むアセンブリを指定する必要があります。
 これは、最も標準的な `mscorlib.dll` や `System.Runtime.dll` にも当てはまります。
@@ -894,6 +893,25 @@ public struct foo
 注意: 構造体型を使用するには、`System.ValueType` 型への参照が解決される必要があります。
 `mscorlib.dll` 又は `System.Private.CoreLib.dll` への参照を追加して下さい。
 
+### 型の参照について
+
+chibildは、任意の型・グローバル変数・関数（これらをメンバーと呼称します）を検索する際に、以下のように検索を実行します:
+
+1. 同一のオブジェクトファイル内に定義されたメンバーが見つかれば、それを参照します。
+2. 異なる入力に定義されたメンバーが見つかれば、それを参照します。
+3. 見つからないため、エラーが発生します。
+
+基本的には、同一のオブジェクトファイルに定義されたメンバーを優先して参照しますが、
+列挙体型・構造体型・値型の配列型定義は、例外的に以下のように取り扱います。
+
+1. 同一のオブジェクトファイル内に定義され、`file` スコープで定義された型定義は、その定義を優先して参照します。
+2. 異なる入力オブジェクトに定義された、 `public`または`internal` スコープの型定義、 
+   及び参照アセンブリに定義された `public` スコープの型定義が存在すれば、その定義を参照します。
+3. 見つからないため、エラーが発生します。
+
+上記に加えて、同名の型を定義したとしても、 `file` スコープではない場合は、その定義が無視されます。
+これは、 .NETでは一般的に、型定義は何れかのアセンブリにただ一つ存在することを想定しているため、混乱を避けるためです。
+
 ### 位置情報を明示する
 
 `.file`と`.location`ディレクティブは、シーケンスポイントと呼ばれるデバッグ情報を生成します。

README.md

@@ -602,7 +602,6 @@ Naturally, a reference to `this` must be pushed onto the evaluation stack.
 A list of parameter types is used to identify overloads.
 If no signature is specified and there are multiple overload methods, the wrong method may be selected.
 Generally, the return type is not verified,
-but the return type is also verified to match when using only for the `op_Implicit` and `op_Explicit` methods.
 
 You have to give it containing assembly on command line option `-l`.
 This is true even for the most standard `mscorlib.dll` or `System.Runtime.dll`.
@@ -914,6 +913,29 @@ Naturally, the result of accessing an out of element will be undefined, so care
 Note: To use an structure type, a reference to the `System.ValueType` type must be resolved.
 Add a reference to `mscorlib.dll` or `System.Private.CoreLib.dll`.
 
+### About type references
+
+When chibild searches for any type, global variable, or function (these are called "members"),
+it performs the search as follows:
+
+1. If a defined member is found in the same object file, it will be referenced.
+2. If a member defined for a different input is found, it will be referenced.
+3. An error is generated because it cannot be found.
+
+Basically, preference is given to members defined in the same object file.
+But array, enumeration, structure and value array type are exceptionally handled as follows:
+
+1. Type declared of the `file` scope in same object,
+   referenced to those declaration.
+2. Type declared of the `public` or `internal` scope in different input objects
+   or type definitions of the `public` scope in the referenced assembly,
+   referenced to those declaration.
+3. An error is generated because it cannot be found.
+
+In addition to the above, if a type of the same name is declared but not in the `file` scope,
+the declaration is ignored.
+This is to avoid confusion, since .NET generally expects only one type declaration in any given assembly.
+
 ### Explicitly location information
 
 The file and location directive will emit sequence points into debugging information.