Add section on external (dart-lang#5481)

Fixes dart-lang#5478 --------- Co-authored-by: Erik Ernst <[email protected]>
atsansone · Feb 20, 2024 · 4829a94 · 4829a94
1 parent 18350c0
commit 4829a94
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 1 deletion.
diff --git a/src/language/functions.md b/src/language/functions.md
@@ -500,6 +500,28 @@ Iterable<int> naturalsDownFrom(int n) sync* {
 }
 ```
 
+## External functions {#external}
+
+An external function is a function whose body is implemented separately from its
+declaration. Include the `external` keyword before a function declaration, like so:
+
+```dart
+external void someFunc(int i);
+```
+
+An external function's implementation can come from another Dart library,
+or, more commonly, from another language. In interop contexts, `external`
+introduces type information for foreign functions or values,
+making them usable in Dart. Implementation and usage is
+heavily platform specific, so check out the interop docs on, for example,
+[C][] or [JavaScript][] to learn more.
+
+External functions can be top-level functions, [instance methods][],
+[getters or setters][], or [non-redirecting constructors][].
+An [instance variable][] can be `external` too,
+which is equivalent to an external getter and (if the variable
+is not `final`) an external setter.
+
 [`Iterable`]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/Iterable-class.html
 [`Stream`]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-async/Stream-class.html
 [record]: /language/records#multiple-returns
@@ -511,3 +533,10 @@ Iterable<int> naturalsDownFrom(int n) sync* {
 [conditional expression]: /language/operators#conditional-expressions
 [Flutter]: {{site.flutter}}
 [trailing commas]: /language/collections#lists
+
+[instance methods]: /language/methods#instance-methods
+[getters or setters]: /language/methods#getters-and-setters
+[non-redirecting constructors]: /language/constructors#redirecting-constructors
+[instance variable]: /language/classes#instance-variables
+[C]: /interop/c-interop
+[JavaScript]: /interop/js-interop
diff --git a/src/language/keywords.md b/src/language/keywords.md
@@ -58,7 +58,7 @@ The following table lists the words that the Dart language treats specially.
 [export]: /guides/libraries/create-packages
 [extends]: /language/extend
 [extension]: /language/extension-methods
-[external]: https://spec.dart.dev/DartLangSpecDraft.pdf#External%20Functions
+[external]: /language/functions#external
 [factory]: /language/constructors#factory-constructors
 [false]: /language/built-in-types#booleans
 [final (variable)]: /language/variables#final-and-const