docs on new function metadata API

lynglib/src/commonMain/kotlin/net/sergeych/lyng/Compiler.kt

@@ -11802,7 +11802,19 @@ class Compiler(
         }
 
         /**
-         * Compile [source] and return semantic top-level function metadata without evaluating it.
+         * Resolve semantic metadata for top-level functions in [source] without evaluating it.
+         *
+         * Functions are returned in source order. Their metadata includes annotations, visibility,
+         * generic parameters, parameter declarations and defaults, receiver information, and the
+         * declared or compiler-inferred return type. Annotation names are collected syntactically;
+         * annotation functions and default expressions are not executed.
+         *
+         * This performs parsing, import resolution, and semantic compilation, but does not generate
+         * executable bytecode. Use [compile] when the resulting script must also be executed.
+         *
+         * @param source named Lyng source whose top-level functions should be inspected
+         * @param importManager provider used to resolve the source's imports and external types
+         * @return metadata for each top-level function declaration in source order
          */
         suspend fun resolveFunctionMetadata(
             source: Source,

lynglib/src/commonMain/kotlin/net/sergeych/lyng/ResolvedFunctionMetadata.kt

@@ -12,6 +12,7 @@
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
+ *
  */
 
 package net.sergeych.lyng
@@ -19,9 +20,21 @@ package net.sergeych.lyng
 /**
  * Compiler-resolved metadata for a function parameter.
  *
+ * [type] is the declared element type for a variadic parameter, not its collected local type.
+ * For example, `values: Int...` has a [type] of `Int`, [isEllipsis] is `true`, and the
+ * corresponding entry in [ResolvedFunctionMetadata.functionType] is `Int...`.
+ *
  * [defaultSource] preserves the source expression for tools that generate declarations. It is
  * null for parameters without defaults and may also be null for declarations assembled by a host
  * rather than parsed from source; use [hasDefault] to distinguish those cases.
+ *
+ * @property name parameter name as written in the declaration
+ * @property type compiler-resolved declared type, or the variadic element type when [isEllipsis]
+ * is `true`
+ * @property isEllipsis whether this parameter collects repeated arguments
+ * @property hasDefault whether the declaration supplies a default expression
+ * @property defaultSource exact source text of the default expression, when available
+ * @property pos source position of the parameter declaration
  */
 data class ResolvedFunctionParameter(
     val name: String,
@@ -38,6 +51,18 @@ data class ResolvedFunctionParameter(
  * Unlike the editor Mini-AST, this descriptor contains compiler-resolved parameter and return
  * types, including an inferred return type when inference succeeds. Annotation names describe the
  * declaration syntax; annotation functions are not executed while this metadata is collected.
+ * The descriptor is intended for declaration generators and other embedding tools that need
+ * semantic signatures without running the script.
+ *
+ * @property name declared function name
+ * @property namePos source position of [name]
+ * @property declarationPos source position at the start of the function declaration
+ * @property visibility resolved declaration visibility
+ * @property annotations annotation names in declaration order, without evaluating annotations
+ * @property typeParams resolved generic type parameters, including bounds and defaults
+ * @property parameters resolved parameters in declaration order
+ * @property functionType complete callable type, including receiver, context receivers, variadic
+ * markers, and the declared or inferred return type
  */
 data class ResolvedFunctionMetadata(
     val name: String,
@@ -49,5 +74,6 @@ data class ResolvedFunctionMetadata(
     val parameters: List<ResolvedFunctionParameter>,
     val functionType: TypeDecl.Function,
 ) {
+    /** Declared or compiler-inferred return type of this function. */
     val returnType: TypeDecl get() = functionType.returnType
 }

lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt

@@ -19,17 +19,16 @@ package net.sergeych.lyng
 
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.yield
-import net.sergeych.lyng.Script.Companion.defaultImportManager
 import net.sergeych.lyng.bridge.bind
 import net.sergeych.lyng.bridge.bindObject
+import net.sergeych.lyng.bytecode.BytecodeLambdaCallable
 import net.sergeych.lyng.bytecode.CmdFunction
 import net.sergeych.lyng.bytecode.CmdVm
-import net.sergeych.lyng.bytecode.BytecodeLambdaCallable
 import net.sergeych.lyng.miniast.*
 import net.sergeych.lyng.obj.*
+import net.sergeych.lyng.pacman.ImportManager
 import net.sergeych.lyng.serialization.ObjJsonClass
 import net.sergeych.lyng.serialization.bindSerializationFormat
-import net.sergeych.lyng.pacman.ImportManager
 import net.sergeych.lyng.stdlib_included.complexLyng
 import net.sergeych.lyng.stdlib_included.decimalLyng
 import net.sergeych.lyng.stdlib_included.legacyDigestLyng
@@ -55,7 +54,15 @@ class Script(
 ) : Statement() {
     fun statements(): List<Statement> = statements
 
-    /** Compiler-resolved metadata for top-level function declarations in source order. */
+    /**
+     * Return compiler-resolved metadata for this script's top-level function declarations.
+     *
+     * Results retain source order and include declared or inferred signature types. This is a
+     * read-only view of information produced while compiling the script; calling it does not
+     * execute the script, its annotations, or parameter default expressions.
+     *
+     * @return metadata for every top-level function declaration in source order
+     */
     fun resolvedFunctionMetadata(): List<ResolvedFunctionMetadata> =
         statements.filterIsInstance<FunctionDeclStatement>().map { it.spec.resolvedMetadata }