Support doc comments on functions

[chinedufn]

Support doc comments on functions

[Jomy10]

I was going to recommend this feature! Could be a nice quality of life improvement.

[chinedufn]

Here's a good-first-issue guide on how to implement this feature.

Implementation Guide

Background Reading

We already parse doc comments for opaque types. Parsing doc comments on functions should work similarly.

swift-bridge/crates/swift-bridge-ir/src/parse/parse_extern_mod/opaque_type_attributes.rs

Lines 11 to 14 in 07a15d7

	/// A doc comment.
	// TODO: Use this to generate doc comment for the generated Swift type.
	#[allow(unused)]
	pub doc_comment: Option<String>,

swift-bridge/crates/swift-bridge-ir/src/parse/parse_extern_mod/opaque_type_attributes.rs

Lines 37 to 70 in 07a15d7

	impl OpaqueTypeAllAttributes {
	pub(super) fn from_attributes(attribs: &[Attribute]) -> Result<Self, syn::Error> {
	let mut attributes = OpaqueTypeAllAttributes::default();
	for attr in attribs.iter() {
	let attribute_name = attr.path.to_token_stream().to_string();
	match attribute_name.as_str() {
	"doc" => {
	let meta = attr.parse_meta()?;
	let doc = match meta {
	Meta::NameValue(name_val) => match name_val.lit {
	syn::Lit::Str(comment) => comment.value(),
	_ => {
	todo!("Push parse error that doc attribute is in incorrect format")
	}
	},
	_ => {
	todo!("Push parse error that doc attribute is in incorrect format")
	}
	};
	attributes.doc_comment = Some(doc);
	}
	"swift_bridge" => {
	attributes.swift_bridge = attr.parse_args()?;
	}
	_ => todo!("Push unsupported attribute error."),
	};
	}
	Ok(attributes)
	}
	}

swift-bridge/crates/swift-bridge-ir/src/parse/parse_extern_mod.rs

Lines 886 to 912 in 3c0d00d

	/// Verify that we can parse a doc comment from an extern "Rust" opaque type.
	#[test]
	fn parse_opaque_rust_type_doc_comment() {
	let tokens = quote! {
	mod foo {
	extern "Rust" {
	/// Some comment
	type AnotherType;
	}
	}
	};
	let module = parse_ok(tokens);
	assert_eq!(
	module
	.types
	.get("AnotherType")
	.unwrap()
	.unwrap_opaque()
	.attributes
	.doc_comment
	.as_ref()
	.unwrap(),
	" Some comment"
	);
	}

Implementing for Functions

Doc Attribute

Add a FunctionAttributes.doc_comment: Option<String>

swift-bridge/crates/swift-bridge-ir/src/parse/parse_extern_mod/function_attributes.rs

Lines 6 to 17 in 3018fc2

	#[derive(Default)]
	pub(super) struct FunctionAttributes {
	pub associated_to: Option<Ident>,
	pub is_swift_initializer: bool,
	pub is_swift_identifiable: bool,
	pub rust_name: Option<LitStr>,
	pub swift_name: Option<LitStr>,
	pub return_into: bool,
	pub return_with: Option<Path>,
	pub args_into: Option<Vec<Ident>>,
	pub get_field: Option<GetField>,
	}

Add a FunctionAttribute::Doc(String)

swift-bridge/crates/swift-bridge-ir/src/parse/parse_extern_mod/function_attributes.rs

Lines 50 to 61 in 3018fc2

	pub(super) enum FunctionAttr {
	AssociatedTo(Ident),
	SwiftName(LitStr),
	RustName(LitStr),
	Init,
	Identifiable,
	ReturnInto,
	ReturnWith(Path),
	ArgsInto(Vec<Ident>),
	GetField(GetFieldDirect),
	GetFieldWith(GetFieldWith),
	}

Parser Test

Add a parser test verifying that we can parse doc comments on a function in an extern "Rust" block.

Our test can use a multi-line doc comment.

Here's an example of a parser test that we can use as inspiration for this new test:

swift-bridge/crates/swift-bridge-ir/src/parse/parse_extern_mod/function_attributes.rs

Lines 516 to 535 in 3018fc2

	/// Verify that we can parse a function that has multiple swift_bridge attributes.
	#[test]
	fn parses_multiple_function_swift_bridge_attributes() {
	let tokens = quote! {
	#[swift_bridge::bridge]
	mod ffi {
	extern "Rust" {
	#[swift_bridge(args_into = (a), return_into)]
	fn some_function(a: u8);
	}
	}
	};
	let module = parse_ok(tokens);
	let func = &module.functions[0];
	assert_eq!(func.args_into.as_ref().unwrap().len(), 1);
	assert_eq!(func.return_into, true);
	}

We can pass the test by parsing the doc comment somewhere around here

swift-bridge/crates/swift-bridge-ir/src/parse/parse_extern_mod/function_attributes.rs

Lines 82 to 94 in 3018fc2

	let attrib = match key.to_string().as_str() {
	"associated_to" => {
	input.parse::<Token![=]>()?;
	let value: Ident = input.parse()?;
	FunctionAttr::AssociatedTo(value)
	}
	"swift_name" => {
	input.parse::<Token![=]>()?;
	let value: LitStr = input.parse()?;
	FunctionAttr::SwiftName(value)
	}

Codegen Test

Add a function attribute codegen test where we test that we emit a doc comment on the generated Swift function.

We can use ExpectedRustTokens::SkipTest since we're mainly concerned with the generated Swift code.

We should use a multi line doc comment in our test.

Here's an example of a function attribute codegen test. Our doc comment test can live near here.

swift-bridge/crates/swift-bridge-ir/src/codegen/codegen_tests/function_attribute_codegen_tests.rs

Lines 398 to 463 in 5b97b4a

	/// Tests that the swift_name function attribute generates the correct code
	/// when using extern "Rust" (calling Rust code from Swift) and when using
	/// extern "Swift" (calling Swift code from Rust).
	mod function_attribute_swift_name_extern_rust {
	use super::*;
	fn bridge_module_tokens() -> TokenStream {
	quote! {
	mod ffi {
	extern "Rust" {
	#[swift_bridge(swift_name = "callRustFromSwift")]
	fn call_rust_from_swift() -> String;
	}
	extern "Swift" {
	#[swift_bridge(swift_name = "callSwiftFromRust")]
	fn call_swift_from_rust() -> String;
	}
	}
	}
	}
	fn expected_rust_tokens() -> ExpectedRustTokens {
	ExpectedRustTokens::Contains(quote! {
	#[export_name = "__swift_bridge__$call_rust_from_swift"]
	pub extern "C" fn __swift_bridge__call_rust_from_swift() -> * mut swift_bridge::string::RustString {
	swift_bridge::string::RustString(super::call_rust_from_swift()).box_into_raw()
	}
	pub fn call_swift_from_rust() -> String {
	unsafe { Box::from_raw(unsafe {__swift_bridge__call_swift_from_rust () }).0 }
	}
	extern "C" {
	#[link_name = "__swift_bridge__$call_swift_from_rust"]
	fn __swift_bridge__call_swift_from_rust() -> * mut swift_bridge::string::RustString;
	}
	})
	}
	fn expected_swift_code() -> ExpectedSwiftCode {
	ExpectedSwiftCode::ContainsAfterTrim(
	r#"
	public func callRustFromSwift() -> RustString {
	RustString(ptr: __swift_bridge__$call_rust_from_swift())
	}
	@_cdecl("__swift_bridge__$call_swift_from_rust")
	func __swift_bridge__call_swift_from_rust () -> UnsafeMutableRawPointer {
	{ let rustString = callSwiftFromRust().intoRustString(); rustString.isOwned = false; return rustString.ptr }()
	}
	"#,
	)
	}
	fn expected_c_header() -> ExpectedCHeader {
	ExpectedCHeader::SkipTest
	}
	#[test]
	fn function_args_into_attribute() {
	CodegenTest {
	bridge_module: bridge_module_tokens().into(),
	expected_rust_tokens: expected_rust_tokens(),
	expected_swift_code: expected_swift_code(),
	expected_c_header: expected_c_header(),
	}
	.test();
	}
	}

Pass Tests

Once the parser and codegen tests are passing we can consider this issue complete.