Doc: Add sugar and desugar notes about async and await

marker_api/src/ast/expr.rs

@@ -379,7 +379,7 @@ mod test {
         assert_eq!(48, size_of::<StrLitExpr<'_>>(), "StrLitExpr<'_>");
         assert_eq!(24, size_of::<CharLitExpr<'_>>(), "CharLitExpr<'_>");
         assert_eq!(24, size_of::<BoolLitExpr<'_>>(), "BoolLitExpr<'_>");
-        assert_eq!(88, size_of::<BlockExpr<'_>>(), "BlockExpr<'_>");
+        assert_eq!(96, size_of::<BlockExpr<'_>>(), "BlockExpr<'_>");
         assert_eq!(88, size_of::<ClosureExpr<'_>>(), "ClosureExpr<'_>");
         assert_eq!(40, size_of::<UnaryOpExpr<'_>>(), "UnaryOpExpr<'_>");
         assert_eq!(40, size_of::<RefExpr<'_>>(), "RefExpr<'_>");

marker_api/src/ast/expr/block_expr.rs

@@ -33,6 +33,9 @@ use super::{CommonExprData, ExprKind};
 /// expression at the end of a block is called *block expression*. The meaning
 /// depends on the context. Marker's documentation will try to make the meaning
 /// clear by linking directly to the [`BlockExpr`] struct or calling it a *block*.
+///
+/// This expression also represents async blocks, the internal desugar used by
+/// rustc is resugared for this.
 #[repr(C)]
 #[derive(Debug)]
 pub struct BlockExpr<'ast> {

marker_api/src/ast/expr/op_exprs.rs

@@ -303,7 +303,25 @@ impl<'ast> AssignExpr<'ast> {
     }
 }
 
-/// TODO: Docs!
+/// An `.await` expression on a future, like:
+///
+/// ```
+/// # async fn foo() -> u8 {
+/// #     16
+/// # }
+/// # async fn wrapper() {
+/// // The await expression
+/// //  vvvvvvvvvvv
+///     foo().await;
+/// //  ^^^^^
+/// // The future, that will be awaited
+/// # }
+/// ```
+///
+/// Marker specificity hides the desugar of `.await` expressions. The [Rust Reference]
+/// contains more information how rustc desugars `.await` expressions.
+///
+/// [Rust Reference]: <https://doc.rust-lang.org/reference/expressions/await-expr.html>
 #[repr(C)]
 #[derive(Debug)]
 pub struct AwaitExpr<'ast> {

marker_api/src/ast/item/fn_item.rs

@@ -24,8 +24,20 @@ use super::CommonItemData;
 ///     // A function without a body
 ///     fn baz(_: i32);
 /// }
+///
+/// // An async function.
+/// async fn foo_async() -> u8 {
+///     // ...
+///     # 16
+/// }
 /// ```
 ///
+/// Async functions in Rustc actually return a future with the defined output type.
+/// The return type `-> u8` gets desugared to `impl Future<Output = u8>`. Marker will
+/// resugar the type to what the user had originally written. In this case it would
+/// just return `u8`. The semantic return type of an async function can be retrieved
+/// from the expression of the [`Body`][super::Body].
+///
 /// See: <https://doc.rust-lang.org/reference/items/functions.html>
 #[repr(C)]
 #[derive(Debug)]

marker_rustc_driver/src/conversion/marker/expr.rs

@@ -524,7 +524,7 @@ impl<'ast, 'tcx> MarkerConverterInner<'ast, 'tcx> {
     /// // Note that both `lhs` have different IDs
     /// ```
     ///
-    /// [Playground]: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=aea16a442e31ca5e7bed1040e8960d4e
+    /// [Playground]: <https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=aea16a442e31ca5e7bed1040e8960d4e>
     #[must_use]
     fn to_assign_expr_from_desugar(&self, block: &hir::Block<'tcx>) -> AssignExpr<'ast> {
         let lhs_map: FxHashMap<_, _> = block

marker_uilints/tests/ui/expr/print_async_block.rs

@@ -1,3 +1,3 @@
 fn something(x: &u8) {
     let _print_async_block = async move { *x };
-}
+}