Document packaging vs structure PackagingMethod split in ScalaDoc

Done by Codex

Author: unkarjedy

packaging/src/main/scala/org/jetbrains/sbtidea/packaging/PackagingMethod.scala

@@ -2,6 +2,21 @@ package org.jetbrains.sbtidea.packaging
 
 import sbt.Project
 
+/**
+  * User-facing, sbt-bound packaging model used in sbt settings (for example, `packageMethod := ...`).
+  *
+  * This type intentionally depends on sbt API (`MergeIntoOther` stores an `sbt.Project`) and keeps
+  * user-friendly defaults in constructors (`DepsOnly()` and `Standalone()`), because it is part of the
+  * sbt configuration DSL.
+  *
+  * During extraction this value is converted into the sbt-agnostic
+  * [[org.jetbrains.sbtidea.packaging.structure.PackagingMethod]] by
+  * [[org.jetbrains.sbtidea.packaging.structure.sbtImpl.SbtPackagingStructureExtractor.keys2Structure]].
+  *
+  * History:
+  *  - 2019-08: split into two models (sbt-facing + structure-facing) during structure extraction refactoring.
+  *  - 2021-03: this sbt-facing type was extracted from `PackagingDefs` into its own file.
+  */
 sealed trait PackagingMethod
 
 object PackagingMethod {
@@ -11,4 +26,4 @@ object PackagingMethod {
   final case class MergeIntoOther(project: Project) extends PackagingMethod
   final case class Standalone(targetPath: String = "", static: Boolean = false) extends PackagingMethod
   final case class PluginModule(moduleName: String, static: Boolean = false) extends PackagingMethod
-}
+}

packaging/src/main/scala/org/jetbrains/sbtidea/packaging/structure/PackagingMethod.scala

@@ -1,5 +1,11 @@
 package org.jetbrains.sbtidea.packaging.structure
 
+/**
+  * Internal, sbt-agnostic packaging model used by extracted project structure.
+  *
+  * See [[org.jetbrains.sbtidea.packaging.PackagingMethod]] for the rationale and the difference
+  * between sbt-facing and structure-facing representations.
+  */
 sealed trait PackagingMethod
 
 object PackagingMethod {