diff --git a/core/src/main/scala/coursier/core/Definitions.scala b/core/src/main/scala/coursier/core/Definitions.scala
index 223aa8d2d..cffbb5fb2 100644
--- a/core/src/main/scala/coursier/core/Definitions.scala
+++ b/core/src/main/scala/coursier/core/Definitions.scala
@@ -1,5 +1,14 @@
 package coursier.core
 
+/**
+ * Identify a "module".
+ *
+ * During resolution, all dependencies having the same module
+ * will be given the same version, if there are no version conflicts
+ * between them.
+ *
+ * Ivy attributes would land here, if support for Ivy is added.
+ */
 case class Module(organization: String,
                   name: String) {
 
@@ -12,6 +21,12 @@ case class Module(organization: String,
 
 sealed abstract class Scope(val name: String)
 
+/**
+ * Dependencies with the same @module will typically see their @version-s merged.
+ *
+ * The remaining fields are left untouched, some being transitively
+ * propagated (exclusions, optional, in particular).
+ */
 case class Dependency(module: Module,
                       version: String,
                       scope: Scope,