Some changes in the rust documentation and its README

api/sixtyfps-rs/README.md

@@ -12,12 +12,43 @@ The complete Rust documentation can be viewed online at https://www.sixtyfps.io/
 
 ## Getting Started
 
-The [crate documentation](https://www.sixtyfps.io/docs/rust/sixtyfps/) shows to be used.
+The [crate documentation](https://www.sixtyfps.io/docs/rust/sixtyfps/) shows how to use this crate.
 
-You can quickly try out the [examples](/examples) by cloning this repo and running the following command:
+### Hello World
+
+The most basic "Hello world" application can easily be achieve in a few lines of code:
+
+In your `Cargo.toml` add:
+
+```toml
+[dependencies]
+sixtyfps = "0.0.1"
+```
+
+And in your `main.rs`:
+
+```rust
+sixtyfps::sixtyfps!{
+    HelloWorld := Window {
+        Text {
+            text: "hello world";
+            color: green;
+        }
+    }
+}
+fn main() {
+    HelloWorld::new().run()
+}
+```
+
+The [`sixtyfps` crate documentation](https://www.sixtyfps.io/docs/rust/sixtyfps/)
+contains more advanced examples and alternative ways to use this crate.
+
+## More examples
+
+You can quickly try out the [examples](/examples) by cloning this repo and running them with `cargo run`
 
 ```sh
 # Runs the "printerdemo" example
-cargo run --release --bin printerdemo
+cargo run --release --bin printerdem
 ```
-

api/sixtyfps-rs/docs.rs

@@ -0,0 +1,105 @@
+#![cfg(doc)]
+/*!
+    This is a pseudo module which only exist for documentation purposes as a way to show
+    the SixtyFPS documentation as part of rustdoc.
+
+    - The [`generated_code`] module contains an [commented example](generated_code::SampleComponent)
+      of what is generated from the `.60` file
+    - The [`langref`] module is the reference documentation for the `.60` language.
+    - The [`widgets`] and [`builtin_elements`] modules contains the documentation of elements usable
+      within the `.60` files
+*/
+
+pub mod langref {
+    #![doc(include = "docs/langref.md")]
+    #![doc = ""]
+}
+
+#[cfg(all(doc, nightly))]
+pub mod builtin_elements {
+    #![doc(include = "docs/builtin_elements.md")]
+    #![doc = ""]
+}
+
+#[cfg(all(doc, nightly))]
+pub mod widgets {
+    #![doc(include = "docs/widgets.md")]
+    #![doc = ""]
+}
+
+/// This module exists only to explain the API of the code generated from `.60` design markup. Its described structure
+/// is not really contained in the compiled crate.
+
+pub mod generated_code {
+
+    use crate::re_exports;
+
+    /// This an example of the API that is generated for a component in `.60` design markup. This may help you understand
+    /// what functions you can call and how you can pass data in and out.
+    /// This is the source code:
+    /// ```60
+    /// SampleComponent := Window {
+    ///     property<int> counter;
+    ///     property<string> user_name;
+    ///     signal hello;
+    ///     /// ... maybe more elements here
+    /// }
+    /// ```
+    pub struct SampleComponent {}
+    impl SampleComponent {
+        /// Creates a new instance that is reference counted and pinned in memory.
+        pub fn new() -> core::pin::Pin<std::rc::Rc<Self>> {
+            unimplemented!()
+        }
+        /// Creates a window on the screen, renders this component in it and spins an event loop to react
+        /// to user input. A typical sequence of creating an instance and showing it may look like this:
+        /// ```ignore
+        /// fn main() {
+        ///     let sample = SampleComponent::new();
+        ///     /// other setup code here, connect to signal handlers, set property values
+        ///     sample.run();
+        /// }
+        /// ```
+        pub fn run(self: core::pin::Pin<std::rc::Rc<Self>>) {}
+        /// Returns a weak pointer for an instance of this component. You can use this to in captures of
+        /// closures, for example signal handlers, to access the component later.
+        pub fn as_weak(self: core::pin::Pin<std::rc::Rc<Self>>) -> re_exports::PinWeak<Self> {
+            unimplemented!()
+        }
+        /// A getter is generated for each property declared at the root of the component.
+        /// In this case, this is the getter that returns the value of the `counter`
+        /// property declared in the `.60` design markup.
+        pub fn get_counter(self: ::core::pin::Pin<&Self>) -> i32 {
+            unimplemented!()
+        }
+        /// A setter is generated for each property declared at the root of the component,
+        /// In this case, this is the setter that sets the value of the `counter` property
+        /// declared in the `.60` design markup.
+        pub fn set_counter(&self, value: i32) {}
+        /// Returns the value of the `user_name` property declared in the `.60` design markup.
+        pub fn get_user_name(self: ::core::pin::Pin<&Self>) -> re_exports::SharedString {
+            unimplemented!()
+        }
+        /// Assigns a new value to the `user_name` property.
+        pub fn set_user_name(&self, value: re_exports::SharedString) {}
+        /// For each signal declared at the root of the component, a function to emit that
+        /// signal is generated. This is the function that emits the `hello` signal declared
+        /// in the `.60` design markup.
+        pub fn emit_hello(self: ::core::pin::Pin<&Self>) {}
+        /// For each signal declared at the root of the component, a function connect to that signal
+        /// is generated. This is the function that registers the function f as callback when the
+        /// signal `hello` is emitted. In order to access
+        /// the component in the callback, you'd typically capture a weak reference obtained using
+        /// [`SampleComponent::as_weak`]
+        /// and then upgrade it to a strong reference when the callback is run:
+        /// ```ignore
+        ///     let sample = SampleComponent::new();
+        ///     let sample_weak = sample.clone().as_weak();
+        ///     sample.as_ref().on_hello(move || {
+        ///         let sample = sample_weak.upgrade().unwrap();
+        ///         sample.as_ref().set_counter(42);
+        ///     });
+        /// ```
+        pub fn on_hello(self: ::core::pin::Pin<&Self>, f: impl Fn() + 'static) {}
+    }
+}

api/sixtyfps-rs/lib.rs

@@ -13,7 +13,7 @@ LICENSE END */
 This crate is the main entry point for embedding user interfaces designed with
 [SixtyFPS UI](https://www.sixtyfps.io/) in Rust programs.
 
-Included in this documentation is also the [language reference](langref/index.html).
+Included in this documentation is also the [language reference](docs::langref).
 
 ## How to use:
 
@@ -25,7 +25,7 @@ of including the design in Rust:
 
  This markup code is translated to Rust code and each component is turned into a Rust
  struct with functions to instantiated, show or access properties. This documentation
- includes an [example][`generated_code::SampleComponent`] of how the API looks
+ includes an [example](docs::generated_code::SampleComponent) of how the API looks
  like.
 
 ### The .60 code in a macro
@@ -34,11 +34,13 @@ This method combines your Rust code with the `.60` design markup in one file, us
 
 ```rust
 sixtyfps::sixtyfps!{
-    HelloWorld := Text {
+    HelloWorld := Window {
+        Text {
             text: "hello world";
             color: green;
         }
     }
+}
 fn main() {
 #   return; // Don't run a window in an example
     HelloWorld::new().run()
@@ -71,7 +73,7 @@ In the `build.rs` file:
 
 ```ignore
 fn main() {
-    sixtyfps_build::compile("ui/hello.60");
+    sixtyfps_build::compile("ui/hello.60").unwrap();
 }
 ```
 
@@ -235,6 +237,8 @@ pub mod testing {
 /// Include the code generated with the sixtyfps-build crate from the build script. After calling `sixtyfps_build::compile`
 /// in your `build.rs` build script, the use of this macro includes the generated Rust code and makes the exported types
 /// available for you to instantiate.
+///
+/// Check the documentation of the `sixtyfps-build` crate for more information.
 #[macro_export]
 macro_rules! include_modules {
     () => {
@@ -251,95 +255,4 @@ pub struct VersionCheck_0_0_1;
 mod compile_fail_tests;
 
 #[cfg(all(doc, nightly))]
-pub mod langref {
+pub mod docs;
-    #![doc(include = "docs/langref.md")]
-    #![doc = ""]
-}
-
-#[cfg(all(doc, nightly))]
-pub mod builtin_elements {
-    #![doc(include = "docs/builtin_elements.md")]
-    #![doc = ""]
-}
-
-#[cfg(all(doc, nightly))]
-pub mod widgets {
-    #![doc(include = "docs/widgets.md")]
-    #![doc = ""]
-}
-
-/// This module exists only to explain the API of the code generated from `.60` design markup. Its described structure
-/// is not really contained in the compiled crate.
-#[cfg(doc)]
-pub mod generated_code {
-    /// This an example of the API that is generated for a component in `.60` design markup. This may help you understand
-    /// what functions you can call and how you can pass data in and out.
-    /// This is the source code:
-    /// ```60
-    /// SampleComponent := Window {
-    ///     property<int> counter;
-    ///     property<string> user_name;
-    ///     signal hello;
-    ///     /// ... maybe more elements here
-    /// }
-    /// ```
-    pub struct SampleComponent {}
-    impl SampleComponent {
-        /// Creates a new instance that is reference counted and pinned in memory.
-        pub fn new() -> core::pin::Pin<std::rc::Rc<Self>> {
-            unimplemented!()
-        }
-        /// Creates a window on the screen, renders this component in it and spins an event loop to react
-        /// to user input. A typical sequence of creating an instance and showing it may look like this:
-        /// ```ignore
-        /// fn main() {
-        ///     let sample = SampleComponent::new();
-        ///     /// other setup code here, connect to signal handlers, set property values
-        ///     sample.run();
-        /// }
-        /// ```
-        pub fn run(self: core::pin::Pin<std::rc::Rc<Self>>) {}
-        /// Returns a weak pointer for an instance of this component. You can use this to in captures of
-        /// closures, for example signal handlers, to access the component later.
-        pub fn as_weak(
-            self: core::pin::Pin<std::rc::Rc<Self>>,
-        ) -> super::re_exports::PinWeak<Self> {
-            unimplemented!()
-        }
-        /// A getter is generated for each property declared at the root of the component.
-        /// In this case, this is the getter that returns the value of the `counter`
-        /// property declared in the `.60` design markup.
-        pub fn get_counter(self: ::core::pin::Pin<&Self>) -> i32 {
-            unimplemented!()
-        }
-        /// A setter is generated for each property declared at the root of the component,
-        /// In this case, this is the setter that sets the value of the `counter` property
-        /// declared in the `.60` design markup.
-        pub fn set_counter(&self, value: i32) {}
-        /// Returns the value of the `user_name` property declared in the `.60` design markup.
-        pub fn get_user_name(self: ::core::pin::Pin<&Self>) -> super::re_exports::SharedString {
-            unimplemented!()
-        }
-        /// Assigns a new value to the `user_name` property.
-        pub fn set_user_name(&self, value: super::re_exports::SharedString) {}
-        /// For each signal declared at the root of the component, a function to emit that
-        /// signal is generated. This is the function that emits the `hello` signal declared
-        /// in the `.60` design markup.
-        pub fn emit_hello(self: ::core::pin::Pin<&Self>) {}
-        /// For each signal declared at the root of the component, a function connect to that signal
-        /// is generated. This is the function that registers the function f as callback when the
-        /// signal `hello` is emitted. In order to access
-        /// the component in the callback, you'd typically capture a weak reference obtained using
-        /// [`SampleComponent::as_weak`]
-        /// and then upgrade it to a strong reference when the callback is run:
-        /// ```ignore
-        ///     let sample = SampleComponent::new();
-        ///     let sample_weak = sample.clone().as_weak();
-        ///     sample.as_ref().on_hello(move || {
-        ///         let sample = sample_weak.upgrade().unwrap();
-        ///         sample.as_ref().set_counter(42);
-        ///     });
-        /// ```
-        pub fn on_hello(self: ::core::pin::Pin<&Self>, f: impl Fn() + 'static) {}
-    }
-}

api/sixtyfps-rs/sixtyfps-build/lib.rs

@@ -12,6 +12,40 @@ LICENSE END */
 It is meant to allow you to compile the `.60` files from your `build.rs`script.
 
 The main entry point of this crate is the [`compile()`] function
+
+## Example
+
+In your Cargo.toml:
+
+```toml
+[package]
+...
+build = "build.rs"
+
+[dependencies]
+sixtyfps = "0.0.1"
+...
+
+[build-dependencies]
+sixtyfps-build = "0.0.1"
+```
+
+In the `build.rs` file:
+
+```ignore
+fn main() {
+    sixtyfps_build::compile("ui/hello.60").unwrap();
+}
+```
+
+Then in your main file
+
+```ignore
+sixtyfps::include_modules!();
+fn main() {
+    HelloWorld::new().run()
+}
+```
 */
 
 #![warn(missing_docs)]
@@ -87,12 +121,24 @@ impl<Sink: Write> Write for CodeFormatter<Sink> {
 
 /// Compile the `.60` file and generate rust code for it.
 ///
-/// The path is relative to the `CARGO_MANIFEST_DIR`.
+/// The generated code code will be created in the directory specified by
+/// the `OUT` environment variable as it is expected for build script.
 ///
-/// The following line need to be added within your crate to include the generated code.
+/// The following line need to be added within your crate in order to include
+/// the generated code.
 /// ```ignore
 /// sixtyfps::include_modules!();
 /// ```
+///
+/// The path is relative to the `CARGO_MANIFEST_DIR`.
+///
+/// In case of compilation error, the errors are shown in `stderr`, the error
+/// are also returned in the [`CompileError`] enum. You must `unwrap` the returned
+/// result to make sure that cargo make the compilation fail in case there were
+/// errors when generating the code.
+///
+/// Please check out the documentation of the `sixtyfps` crate for more information
+/// about how to use the generated code.
 pub fn compile(path: impl AsRef<std::path::Path>) -> Result<(), CompileError> {
     compile_with_config(path, Default::default())
 }

api/sixtyfps-rs/sixtyfps-docs-integration.html

@@ -1,3 +1,7 @@
+<!--
+    This file is used to add preview of the `.60` snippets in the generated rustdoc documentation.
+    It can be injected via the `--html-in-header sixtyfps-docs-integration.html` option of rustdoc.
+-->
 <script type="module">
     "use strict";
     import * as sixtyfps from 'https://www.sixtyfps.io/wasm-interpreter/sixtyfps_wasm_interpreter.js';

api/sixtyfps-rs/sixtyfps-macros/lib.rs

@@ -7,6 +7,15 @@
     This file is also available under commercial licensing terms.
     Please contact info@sixtyfps.io for more information.
 LICENSE END */
+
+/*!
+
+*NOTE*: This library is an internal crate for the [SixtyFPS project](https://sixtyfps.io).
+This crate should not be used directly by application using SixtyFPS.
+You should use the `sixtyfps` crate instead.
+
+*/
+
 extern crate proc_macro;
 use proc_macro::{Spacing, TokenStream, TokenTree};
 use quote::ToTokens;
@@ -222,6 +231,9 @@ fn extract_include_paths(
 
 /// This macro allows you to use the `.60` design markup language inline in Rust code. Within the braces of the macro
 /// you can use place `.60` code and the named exported components will be available for instantiation.
+///
+/// [The documentation of the `sixtyfps`](./index.html) crate contains more information about the language specification and
+/// how to use the generated code.
 #[proc_macro]
 pub fn sixtyfps(stream: TokenStream) -> TokenStream {
     let token_iter = stream.into_iter();