Support doc comments in header-translator

Auto-generate documentation comments in translated code. We use
`clang_Cursor_getParsedComment` to parse the comment to avoid the
Sphinx-like syntax (and yeah, that function seems to have a fair number
of bugs, but that can be improved upstream).

Part of #309.
Originally authored in #435.

Co-authored-by: Sebastian Imlay <sebastian.imlay@gmail.com>

Author: madsmtm

crates/header-translator/src/documentation.rs

@@ -60,19 +60,13 @@ fn update_module(module: &mut Module) {
     let mut iter = mem::take(&mut module.stmts).into_iter().peekable();
     while let Some(stmt) = iter.next() {
         if let Stmt::AliasDecl {
-            id,
-            availability: _,
-            ty,
-            kind: None,
+            id, ty, kind: None, ..
         } = &stmt
         {
             if let Some(Stmt::EnumDecl {
                 id: enum_id,
-                availability: _,
                 ty: enum_ty,
-                kind: _,
-                variants: _,
-                sendable: _,
+                ..
             }) = iter.peek_mut()
             {
                 if enum_ty.is_typedef_to(&id.name) {

crates/header-translator/src/global_analysis.rs

@@ -497,22 +497,6 @@ impl ItemIdentifier {
 
         ItemIdentifierPathInRelationTo(self, other)
     }
-
-    /// Generate a markdown link to Apple's documentation.
-    ///
-    /// This is best effort only, and doesn't work for functions and methods,
-    /// and possibly some renamed classes and traits. Additionally, the link
-    /// may redirect.
-    pub(crate) fn doc_link(&self) -> impl fmt::Display + '_ {
-        FormatterFn(|f| {
-            write!(
-                f,
-                "[Apple's documentation](https://developer.apple.com/documentation/{}/{}?language=objc)",
-                self.library_name().to_lowercase(),
-                self.name.to_lowercase()
-            )
-        })
-    }
 }
 
 impl ItemIdentifier<Option<String>> {

crates/header-translator/src/id.rs

@@ -15,6 +15,7 @@ mod cfgs;
 mod config;
 mod context;
 mod display_helper;
+pub mod documentation;
 mod expr;
 mod fn_utils;
 mod global_analysis;

crates/header-translator/src/lib.rs

@@ -457,6 +457,13 @@ see that for related crates.", self.data.krate)?;
             // We don't have the manpower to document the safety of methods.
             writeln!(f, "#![allow(clippy::missing_safety_doc)]")?;
 
+            // Our auto-generated rustdoc is kinda bad.
+            writeln!(f, "#![allow(clippy::doc_lazy_continuation)]")?;
+            writeln!(f, "#![allow(rustdoc::broken_intra_doc_links)]")?;
+            writeln!(f, "#![allow(rustdoc::bare_urls)]")?;
+            writeln!(f, "#![allow(rustdoc::unportable_markdown)]")?;
+            writeln!(f, "#![allow(rustdoc::invalid_html_tags)]")?;
+
             writeln!(f)?;
 
             if self.data.link {

crates/header-translator/src/library.rs

@@ -416,8 +416,14 @@ fn get_translation_unit<'i: 'c, 'c>(
         "-fobjc-exceptions",
         "-fobjc-abi-version=2", // 3??
         "-fblocks",
+        // We're parsing system headers, but still want comments from there.
+        //
+        // See: https://clang.llvm.org/docs/UsersManual.html#comment-parsing-options
+        "-fretain-comments-from-system-headers",
+        // Tell Clang to parse non-doc comments too.
         // "-fparse-all-comments",
-        // TODO: "-fretain-comments-from-system-headers"
+        // Explicitly pass the sysroot (we aren't invoked through
+        // `/usr/bin/clang` which is what usually passes it).
         "-isysroot",
         sdk.path.to_str().unwrap(),
         // See ClangImporter.cpp and Foundation/NSObjCRuntime.h

crates/header-translator/src/main.rs

@@ -6,6 +6,7 @@ use crate::availability::Availability;
 use crate::config::MethodData;
 use crate::context::Context;
 use crate::display_helper::FormatterFn;
+use crate::documentation::Documentation;
 use crate::id::ItemIdentifier;
 use crate::immediate_children;
 use crate::objc2_utils::in_selector_family;
@@ -269,6 +270,7 @@ pub struct Method {
     weak_property: bool,
     must_use: bool,
     encoding: String,
+    documentation: Documentation,
 }
 
 #[derive(Debug)]
@@ -523,6 +525,7 @@ impl Method {
                 weak_property: false,
                 must_use: modifiers.must_use,
                 encoding,
+                documentation: Documentation::from_entity(&entity),
             },
         ))
     }
@@ -587,7 +590,7 @@ impl Method {
 
             Some(Method {
                 selector: getter_sel.clone(),
-                fn_name: getter_sel,
+                fn_name: getter_sel.clone(),
                 availability: availability.clone(),
                 is_class,
                 is_optional: entity.is_objc_optional(),
@@ -603,6 +606,7 @@ impl Method {
                 weak_property: false,
                 must_use: modifiers.must_use,
                 encoding: encoding.clone(),
+                documentation: Documentation::from_entity(&entity),
             })
         } else {
             None
@@ -648,6 +652,7 @@ impl Method {
                     weak_property: attributes.map(|a| a.weak).unwrap_or(false),
                     must_use: modifiers.must_use,
                     encoding,
+                    documentation: Documentation::property_setter(&getter_sel),
                 })
             } else {
                 None
@@ -741,6 +746,7 @@ impl fmt::Display for Method {
         // Attributes
         //
 
+        write!(f, "{}", self.documentation.fmt(None))?;
         write!(f, "{}", self.availability)?;
 
         if self.must_use {