Deployed 7f41fd8 to next with MkDocs 1.6.0 and mike 2.1.1

next/tutorial/Rust_scaffolding.html

@@ -354,17 +354,17 @@
     </span>
   </a>
 
-    <nav class="md-nav" aria-label="Rust scaffolding code for UDL">
-      <ul class="md-nav__list">
-
-          <li class="md-nav__item">
+</li>
+
+        <li class="md-nav__item">
   <a href="#setup-for-crates-using-only-proc-macros" class="md-nav__link">
     <span class="md-ellipsis">
       Setup for crates using only proc macros
     </span>
   </a>
 
-</li>
+    <nav class="md-nav" aria-label="Setup for crates using only proc macros">
+      <ul class="md-nav__list">
 
           <li class="md-nav__item">
   <a href="#libraries-that-depend-on-uniffi-components" class="md-nav__link">
@@ -1440,17 +1440,17 @@
     </span>
   </a>
 
-    <nav class="md-nav" aria-label="Rust scaffolding code for UDL">
-      <ul class="md-nav__list">
-
-          <li class="md-nav__item">
+</li>
+
+        <li class="md-nav__item">
   <a href="#setup-for-crates-using-only-proc-macros" class="md-nav__link">
     <span class="md-ellipsis">
       Setup for crates using only proc macros
     </span>
   </a>
 
-</li>
+    <nav class="md-nav" aria-label="Setup for crates using only proc macros">
+      <ul class="md-nav__list">
 
           <li class="md-nav__item">
   <a href="#libraries-that-depend-on-uniffi-components" class="md-nav__link">
@@ -1485,8 +1485,8 @@
 
 
 <h1 id="rust-scaffolding">Rust scaffolding</h1>
-<p>As already noted UniFFI supports two methods of interface definitions: UDL files and proc macros.</p>
-<p>If you use proc macros you can skip the next section, but if you use UDL files, you need to generate Rust "scaffolding" - code to implement what's described in the UDL.</p>
+<p>UniFFI requires that our generated Rust "scaffolding" code is included in your project. For proc macros, most of this is conveniently generated by the macros.</p>
+<p>If you use UDL files, you need to generate this "scaffolding" then include the generated .rs in your project.</p>
 <h2 id="rust-scaffolding-code-for-udl">Rust scaffolding code for UDL</h2>
 <p>Crates using UDL need a <code>build.rs</code> file next to <code>Cargo.toml</code>. This uses <code>uniffi</code> to generate the Rust scaffolding code.</p>
 <div class="highlight"><pre><span></span><code><span class="k">fn</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
@@ -1497,14 +1497,13 @@ <h2 id="rust-scaffolding-code-for-udl">Rust scaffolding code for UDL</h2>
 <p>Lastly, we include the generated scaffolding code in our <code>lib.rs</code> using this handy macro:</p>
 <div class="highlight"><pre><span></span><code><span class="n">uniffi</span><span class="p">::</span><span class="n">include_scaffolding</span><span class="o">!</span><span class="p">(</span><span class="s">&quot;math&quot;</span><span class="p">);</span>
 </code></pre></div>
-<h3 id="setup-for-crates-using-only-proc-macros">Setup for crates using only proc macros</h3>
+<h2 id="setup-for-crates-using-only-proc-macros">Setup for crates using only proc macros</h2>
 <p>If you are only using proc macros, you can skip <code>build.rs</code> entirely!
 All you need to do is add this to the top of <code>lib.rs</code></p>
 <div class="highlight"><pre><span></span><code><span class="n">uniffi</span><span class="p">::</span><span class="n">setup_scaffolding</span><span class="o">!</span><span class="p">();</span>
 </code></pre></div>
-<p>NOTE: This function takes an optional parameter, the <a href="../udl/namespace.html"><code>namespace</code></a> used by the component.
-If not specified, the crate name will be used as the namespace.</p>
-<p><strong>⚠ Warning ⚠</strong> Do not call both <code>uniffi::setup_scaffolding!()</code> and <code>uniffi::include_scaffolding!!()</code> in the same crate.</p>
+<p>Don't use <code>uniffi::setup_scaffolding!()</code> in a crate which uses <code>uniffi::include_scaffolding!()</code>.</p>
+<p>If you don't specify a <a href="../udl/namespace.html"><code>namespace</code></a> the crate name is used.</p>
 <h3 id="libraries-that-depend-on-uniffi-components">Libraries that depend on UniFFI components</h3>
 <p>Suppose you want to create a shared library that includes one or more
 components using UniFFI. The typical way to achieve this is to create a new

next/tutorial/udl_file.html

@@ -327,9 +327,18 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 
         <li class="md-nav__item">
-  <a href="#the-udl-file" class="md-nav__link">
+  <a href="#proc-macros" class="md-nav__link">
     <span class="md-ellipsis">
-      The UDL File
+      Proc macros
+    </span>
+  </a>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#a-udl-file" class="md-nav__link">
+    <span class="md-ellipsis">
+      A UDL File
     </span>
   </a>
 
@@ -1410,9 +1419,18 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 
         <li class="md-nav__item">
-  <a href="#the-udl-file" class="md-nav__link">
+  <a href="#proc-macros" class="md-nav__link">
     <span class="md-ellipsis">
-      The UDL File
+      Proc macros
+    </span>
+  </a>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#a-udl-file" class="md-nav__link">
+    <span class="md-ellipsis">
+      A UDL File
     </span>
   </a>
 
@@ -1437,10 +1455,14 @@
 
 
 <h1 id="describing-the-interface">Describing the interface</h1>
-<p>There are two ways of describing your interface:
-1 - with a UDL file (a type of IDL, Interface Definition Language);
-2 - with <a href="../proc_macro/index.html">Rust procmacros</a>, similarly to how <code>wasm-bindgen</code> work. This avoids repeating your interface definitions in a separate file. Unfortunately, our docs aren't quite as good for that yet though.</p>
-<h2 id="the-udl-file">The UDL File</h2>
+<p>There are two ways of describing your interface:</p>
+<h2 id="proc-macros">Proc macros</h2>
+<p><a href="../proc_macro/index.html">Rust proc macros</a> can describe your interface - you'd define the function as:</p>
+<div class="highlight"><pre><span></span><code>#[uniffi::export]
+fn add(a: u32, b: u32) -&gt; u32 { a + b }
+</code></pre></div>
+<p>You need to <a href="./Rust_scaffolding.md&quot;">set up the scaffolding</a> with <code>uniffi::setup_scaffolding!()</code> - but that's it.</p>
+<h2 id="a-udl-file">A UDL File</h2>
 <p>We describe in a UDL (a type of IDL, Interface Definition Language) file <em>what</em> is exposed and available to foreign-language bindings. In this case, we are only playing with primitive types (<code>u32</code>) and not custom data structures but we still want to expose the <code>add</code> method.<br />
 Let's create a <code>math.udl</code> file in the <code>math</code> crate's <code>src/</code> folder:</p>
 <div class="highlight"><pre><span></span><code>namespace<span class="w"> </span>math<span class="w"> </span>{

next/udl/namespace.html

@@ -1381,15 +1381,16 @@
 
 
 <h1 id="namespace">Namespace</h1>
+<p>Every crate has a UniFFI "namespace". This is the name exposed to the foreign bindings, typically as a module.</p>
 <p>Every UDL file <em>must</em> have a <code>namespace</code> block:</p>
 <div class="highlight"><pre><span></span><code>namespace<span class="w"> </span>math<span class="w"> </span>{
 <span class="w">  </span><span class="nb">double</span><span class="w"> </span><span class="nb">exp</span>(<span class="nb">double</span><span class="w"> </span>a);
 };
 </code></pre></div>
-<p>It serves multiple purposes:
-- It identifies the name of the generated Rust scaffolding file <code>&lt;namespace&gt;.uniffi.rs</code>.
-- It identifies the package name of the generated foreign-language bindings (e.g. <code>uniffi.&lt;namespace&gt;</code> in Kotlin)
-- It also contains all <a href="functions.html">top-level <em>functions</em></a> that get exposed to foreign-language bindings.</p>
+<p>which might be used as <code>from math import exp</code>/<code>import math</code>/<code>import omg.wtf.math.exp</code> etc.</p>
+<p>Proc macros use the crate name as the namespace by default, but it can be specified with</p>
+<div class="highlight"><pre><span></span><code><span class="n">uniffi</span><span class="p">::</span><span class="n">setup_scaffolding</span><span class="o">!</span><span class="p">(</span><span class="s">&quot;namespace&quot;</span><span class="p">);</span>
+</code></pre></div>