better processing of lyng.d. files

docs/idea_plugin.md

@@ -9,9 +9,12 @@ should be compatible with other IDEA flavors, notably [OpenIDE](https://openide.
 - reformat code (indents, spaces)
 - reformat on paste
 - smart enter key
+- `.lyng.d` definition files (merged into analysis for completion, navigation, Quick Docs, and error checking)
 
 Features are configurable via the plugin settings page, in system settings.
 
+See `docs/lyng_d_files.md` for `.lyng.d` syntax and examples.
+
 > Recommended for IntelliJ-based IDEs: While IntelliJ can import TextMate bundles
 > (Settings/Preferences → Editor → TextMate Bundles), the native Lyng plugin provides
 > better support (formatting, smart enter, background analysis, etc.). Prefer installing
@@ -26,4 +29,4 @@ Features are configurable via the plugin settings page, in system settings.
 
 ### [Download plugin v0.0.2-SNAPSHOT](https://lynglang.com/distributables/lyng-idea-0.0.2-SNAPSHOT.zip)
 
-Your ideas and bugreports are welcome on the [project gitea page](https://gitea.sergeych.net/SergeychWorks/lyng/issues)
+Your ideas and bugreports are welcome on the [project gitea page](https://gitea.sergeych.net/SergeychWorks/lyng/issues)

docs/lyng_d_files.md

@@ -0,0 +1,116 @@
+# `.lyng.d` Definition Files
+
+`.lyng.d` files declare Lyng symbols for tooling without shipping runtime implementations. The IntelliJ IDEA plugin merges
+all `*.lyng.d` files from the current directory and its parent directories into the active file’s analysis, enabling:
+
+- completion
+- navigation
+- error checking for declared symbols
+- Quick Docs for declarations defined in `.lyng.d`
+
+Place `*.lyng.d` files next to the code they describe (or in a parent folder). The plugin will pick them up automatically.
+
+## Writing `.lyng.d` Files
+
+You can declare any language-level symbol in a `.lyng.d` file. Use doc comments before declarations to make Quick Docs
+work in the IDE. The doc parser accepts standard comments (`/** ... */` or `// ...`) and supports tags like `@param`.
+
+### Full Example
+
+```lyng
+/** Library entry point */
+extern fun connect(url: String, timeoutMs: Int = 5000): Client
+
+/** Type alias with generics */
+type NameMap = Map<String, String>
+
+/** Multiple inheritance via interfaces */
+interface A { abstract fun a(): Int }
+interface B { abstract fun b(): Int }
+
+/** A concrete class implementing both */
+class Multi(name: String) : A, B {
+    /** Public field */
+    val id: Int = 0
+    
+    /** Mutable property with accessors */
+    var size: Int
+        get() = 0
+        set(v) { }
+    
+    /** Instance method */
+    fun a(): Int = 1
+    fun b(): Int = 2
+}
+
+/** Nullable and dynamic types */
+extern val dynValue: dynamic
+extern var dynVar: dynamic?
+
+/** Delegated property */
+class LazyBox(val create) {
+    fun getValue(thisRef, name) = create()
+}
+
+val cached by LazyBox { 42 }
+
+/** Delegated function */
+object RpcDelegate {
+    fun invoke(thisRef, name, args...) = Unset
+}
+
+fun remoteCall by RpcDelegate
+
+/** Singleton object */
+object Settings {
+    val version: String = "1.0"
+}
+
+/** Class with documented members */
+class Client {
+    /** Returns a greeting. */
+    fun greet(name: String): String = "hi " + name
+}
+```
+
+See a runnable sample file in `docs/samples/definitions.lyng.d`.
+
+Notes:
+- Use real bodies if the declaration is not `extern` or `abstract`.
+- If you need purely declarative stubs, prefer `extern` members (see `embedding.md`).
+
+## Doc Comment Format
+
+Doc comments are picked up when they immediately precede a declaration.
+
+```lyng
+/**
+ * A sample function.
+ * @param name user name
+ * @return greeting string
+ */
+fun greet(name: String): String = "hi " + name
+```
+
+## Generating `.lyng.d` Files
+
+You can generate `.lyng.d` as part of your build. A common approach is to write a Gradle task that emits a file from a
+template or a Kotlin data model.
+
+Example (pseudo-code):
+
+```kotlin
+tasks.register("generateLyngDefs") {
+    doLast {
+        val out = file("src/main/lyng/api.lyng.d")
+        out.writeText(
+            """
+            /** Generated API */
+            fun ping(): Int
+            """.trimIndent()
+        )
+    }
+}
+```
+
+Place the generated file in your source tree, and the IDE will load it automatically.

docs/samples/definitions.lyng.d

@@ -0,0 +1,65 @@
+/**
+ * Sample .lyng.d file for IDE support.
+ * Demonstrates declarations and doc comments.
+ */
+
+/** Simple function with default and named parameters. */
+extern fun connect(url: String, timeoutMs: Int = 5000): Client
+
+/** Type alias with generics. */
+type NameMap = Map<String, String>
+
+/** Multiple inheritance via interfaces. */
+interface A { abstract fun a(): Int }
+interface B { abstract fun b(): Int }
+
+/** A concrete class implementing both. */
+class Multi(name: String) : A, B {
+    /** Public field. */
+    val id: Int = 0
+
+    /** Mutable property with accessors. */
+    var size: Int
+        get() = 0
+        set(v) { }
+
+    /** Instance method. */
+    fun a(): Int = 1
+    fun b(): Int = 2
+}
+
+/** Nullable and dynamic types. */
+extern val dynValue: dynamic
+extern var dynVar: dynamic?
+
+/** Delegated property provider. */
+class LazyBox(val create) {
+    fun getValue(thisRef, name) = create()
+}
+
+/** Delegated property using provider. */
+val cached by LazyBox { 42 }
+
+/** Delegated function. */
+object RpcDelegate {
+    fun invoke(thisRef, name, args...) = Unset
+}
+
+/** Remote function proxy. */
+fun remoteCall by RpcDelegate
+
+/** Singleton object. */
+object Settings {
+    /** Version string. */
+    val version: String = "1.0"
+}
+
+/**
+ * Client API entry.
+ * @param name user name
+ * @return greeting string
+ */
+class Client {
+    /** Returns a greeting. */
+    fun greet(name: String): String = "hi " + name
+}