Create documentation that describes a module.modulemap, and how to set it up - to provide the module interface to C/ObjC code

[heckj]

Description

Follow-up from #8621, which was referencing what a module is while porting documentation from bare markdown into DocC, and updating it "a smidge".

Per Artem's feedback in that PR:

A module is a unit of code distribution, capturing the API of your library/framework to be used by clients. The description in this section is already a pretty good start.

In Swift, a module is built from a collection of source (.swift) files and captures their public interface to be used by clients and a module typically corresponds to a binary product (e.g. a shared library).

Swift also relies on what we call "Clang modules" as the main mechanism to interact with modularized C/ObjC code. There's documentation on those here: https://clang.llvm.org/docs/Modules.html (not to be confused with C++ standard modules). These are also simply units of code distribution, but unlike Swift, these are hand-authored via a special module-defining file (module.modulemap) and a collection of headers. Clang modules also typically correspond to a binary product though with C-family languages we can have header-only modules/libraries.

The section in "About Modules" in the article Introducing Packages provides some of this detail, but it really begs the question of how you can/should set up such a thing, which seems like it really needs to be it's own article both introducing the more detail, as well as providing a guide on what and how to arrange the module interface.

Expected behavior

documentation for Swift Package Manager in DocC that describes how to add a module interface to C code - either as header-only code (C), header+source (C/ObjC), or binary artifact (ex: system library or .binaryArtifact dependency)

Actual behavior

No response

Steps to reproduce

No response

Swift Package Manager version/commit hash

8694d3c

Swift & OS version (output of swift --version && uname -a)

swift-driver version: 1.120.5 Apple Swift version 6.1.2 (swiftlang-6.1.2.1.2 clang-1700.0.13.5)
Target: arm64-apple-macosx15.0
Darwin Joes-MacBook-Pro-3.local 24.4.0 Darwin Kernel Version 24.4.0: Fri Apr 11 18:32:50 PDT 2025; root:xnu-11417.101.15~117/RELEASE_ARM64_T6041 arm64

[rauhul]

I think its very important for these docs to also include instructions on how to use APINotes.

(Apinotes in swiftPM are buggy, but the doc should explain how they should work, e.g. a spec, and bugs should be opened if SwiftPM doesn't match the spec)

[heckj]

Also related issue: #4755