From 81893e08e5295bcdaee54eb2706d8c3e2f56f876 Mon Sep 17 00:00:00 2001
From: Guille Polito <guillermopolito@gmail.com>
Date: Tue, 1 Oct 2019 12:15:24 +0200
Subject: [PATCH] Documentation: add class comments

---
 src/UnifiedFFI/FFIClassVariableArgument.class.st    | 3 +++
 src/UnifiedFFI/FFIConstantArgument.class.st         | 7 +++++++
 src/UnifiedFFI/FFITypeDeclaration.class.st          | 4 ++++
 src/UnifiedFFI/FFIUndefinedTypeDeclaration.class.st | 7 +++++++
 src/UnifiedFFI/FFIVariableArgument.class.st         | 8 ++++++++
 5 files changed, 29 insertions(+)

diff --git a/src/UnifiedFFI/FFIClassVariableArgument.class.st b/src/UnifiedFFI/FFIClassVariableArgument.class.st
index bb5bcc5defe..1d30c95c6a1 100644
--- a/src/UnifiedFFI/FFIClassVariableArgument.class.st
+++ b/src/UnifiedFFI/FFIClassVariableArgument.class.st
@@ -1,3 +1,6 @@
+"
+I am a loader for class variables, pushing to the stack the class variable literal
+"
 Class {
 	#name : #FFIClassVariableArgument,
 	#superclass : #FFIFunctionArgumentLoader,
diff --git a/src/UnifiedFFI/FFIConstantArgument.class.st b/src/UnifiedFFI/FFIConstantArgument.class.st
index 2343c2be4a4..650cacac400 100644
--- a/src/UnifiedFFI/FFIConstantArgument.class.st
+++ b/src/UnifiedFFI/FFIConstantArgument.class.st
@@ -1,3 +1,10 @@
+"
+I am a function argument representing a literal value (in contrast to a variable).
+The parser creates me when it finds other than symbols as arguments.
+
+I am resolved by resolving my type.
+The type knows how to resolve itself in a context.
+"
 Class {
 	#name : #FFIConstantArgument,
 	#superclass : #FFIFunctionArgument,
diff --git a/src/UnifiedFFI/FFITypeDeclaration.class.st b/src/UnifiedFFI/FFITypeDeclaration.class.st
index 78751cbf2c7..6bdbb621490 100644
--- a/src/UnifiedFFI/FFITypeDeclaration.class.st
+++ b/src/UnifiedFFI/FFITypeDeclaration.class.st
@@ -1,3 +1,7 @@
+"
+I represent a type declaration in a FFI function signature. I have a type name and an arity (the number of indirections indicated by pointer marker stars *).
+I am resolved as an external FFI type with my arity.
+"
 Class {
 	#name : #FFITypeDeclaration,
 	#superclass : #Object,
diff --git a/src/UnifiedFFI/FFIUndefinedTypeDeclaration.class.st b/src/UnifiedFFI/FFIUndefinedTypeDeclaration.class.st
index ff945bcc70c..901f70352f5 100644
--- a/src/UnifiedFFI/FFIUndefinedTypeDeclaration.class.st
+++ b/src/UnifiedFFI/FFIUndefinedTypeDeclaration.class.st
@@ -1,3 +1,10 @@
+"
+I represent the absense of a type declaration.
+I delegate my resolution to the resolver with a double dispatch so it can choose how to resolve non-declared types.
+A resolver (FFICallout) has two main resolution strategies: 
+- strict does not accept resolving undefined types
+- non strict is a backwards compatibility mode that tries to infer the type if possible (but can go wrong and should be used with care)
+"
 Class {
 	#name : #FFIUndefinedTypeDeclaration,
 	#superclass : #Object,
diff --git a/src/UnifiedFFI/FFIVariableArgument.class.st b/src/UnifiedFFI/FFIVariableArgument.class.st
index 39e57fc16b8..7b81a68c08c 100644
--- a/src/UnifiedFFI/FFIVariableArgument.class.st
+++ b/src/UnifiedFFI/FFIVariableArgument.class.st
@@ -1,3 +1,11 @@
+"
+I am a function argument representing a variable (in contrast to a literal value).
+The parser creates me when it finds symbols as arguments.
+
+I am resolved by resolving my type and my name.
+The type knows how to resolve itself in a context.
+To resolve my name, the resolver performs a semantic analysis in the calling context to define if the variable is an instance variable, a method argument or a class variable. The name resolution is represented by my loader.
+"
 Class {
 	#name : #FFIVariableArgument,
 	#superclass : #FFIFunctionArgument,