docs: ClientBootstrap reuse is not important but permissible on the same thread/EL

[weissi]

Motivation:

The original ClientBootstrap documentation is sometimes misunderstood as stressing the importance to re-use.

Modifications:

Explain that reuse is not important but permissible on the same thread/EL.

Result:

Clearer docs.

[tayloraswift]

it would be really great if we could suppress the DocC symbol link warnings, those cross-module/cross-package links work on Swiftinit!

[weissi]

it would be really great if we could suppress the DocC symbol link warnings, those cross-module/cross-package links work on Swiftinit!

@franklinsch is this an option? Or will this work in DocC soon too?

Context is that I had to take out

``Sendable``

and

``EventLoop``

because it complained

[franklinsch]

@weissi We're tracking cross-target link resolution with swiftlang/swift-docc#208. It's being worked on primarily by @d-ronnqvist

[d-ronnqvist]

@weissi We're tracking cross-target link resolution with apple/swift-docc#208. It's being worked on primarily by @d-ronnqvist

The initial support for cross-target linking in DocC is available on main behind a feature flag but the overall feature of multi-target documentation is still in progress.

Note that the planned—and currently implemented—syntax for linking to a symbol in another module is

``/OtherModuleName/SymbolName/functionName()``

stating with a leading / to indicate an external symbol link, followed by the absolute symbol path (including the name of the external module). For example:

• /Swift/Sendable
• /NIOCore/EventLoop

[weissi]

@weissi We're tracking cross-target link resolution with apple/swift-docc#208. It's being worked on primarily by @d-ronnqvist

The initial support for cross-target linking in DocC is available on main behind a feature flag but the overall feature of multi-target documentation is still in progress.

Note that the planned—and currently implemented—syntax for linking to a symbol in another module is

``/OtherModuleName/SymbolName/functionName()``

stating with a leading / to indicate an external symbol link, followed by the absolute symbol path (including the name of the external module). For example:

• /Swift/Sendable
• /NIOCore/EventLoop

@dnadoba I assume NIO isn't using feature flags for its docs right now so this has to stay as is, correct?

[dnadoba]

I'm not aware of any feature flags set for DocC in NIO. The two main way DocC is compiled is through the build system provided by https://swiftpackageindex.com/ and Xcodes "Product -> Build Documentation" action. I'm not aware of a safe way to add flags to both of them.

[tayloraswift]

do these links actually produce any build errors in Xcode?