Address documentation and test organization feedback for layered crate

[Copilot]

Fixes rustdoc warnings for feature-gated types and improves clarity of core concepts documentation.

Documentation improvements

Unresolved link warnings: Conditional cfg_attr attributes now prevent rustdoc warnings when features are disabled. Links to Intercept, DynamicService, and tower module resolve correctly based on active features.

Key Concepts section: Clarified that Service is a trait implementation (not "an async function"), middleware is a service wrapper (not just "adds behavior"), and Layer is a trait that constructs middleware (removed "factory" terminology).

Layers and Middleware example: Added explicit comment identifying the middleware service wrapper to make the pattern concrete.

Test organization

Moved public API tests to tests/ directory:

• Service trait implementations (Box/Arc)
• DynamicService type erasure
• Intercept middleware behavior
• Tower adapter compatibility
• Layer stacking

Internal tests using MockService or testing implementation details remain in source modules.

Changes summary

• lib.rs: Feature doc links now conditional on feature flags
• README.md: Synchronized with lib.rs documentation updates
• tests/*.rs: Five new integration test files covering public APIs
• Source modules: Removed duplicate tests, retained internal-only tests

Original prompt

---

This section details on the original issue you should resolve

<issue_title>layered crate: additional feedback</issue_title>
<issue_description>Sorry, I did not get to review this last week. That said, could we do a follow-up PR addressing a few issues:

• cargo doc gives me various warnings coming from layer, like warning: unresolved link to DynamicService --> crates/layered/src/lib.rs:113:40
• most tests should be moved to tests/
• the "Key Concepts" section is to short and doesn't quite make sense to me. For example, when you write "Service: An async function In → Out that processes inputs" you seem to want to say that a Service acts like a function (as it transforms some input to some output), but clearly it's a type with a trait implementation. I think all of these entries should be more clarified. I also wouldn't use the term "factory".
• The example below that ("Layers and Middleware") doesn't work out well what a middleware actually is. It seems to be left as an exercise for the reader
• Why is Execute called that? Shouldn't this be a ServiceFn or so?

Also, some docs look like so (apparently related to warnings above)

Originally posted by @ralfbiedert in #189 (comment)
</issue_description>

<agent_instructions>Address the feedback as specified in the issue description. Some additional notes:

• Can we optionally disable the unresolved link warning when the docs are not building with all features.
• Move only tests that exercise public API, internal ones or ones that use some internal helper need to stay in respective modules.
• Improve the docs.
• Improve the example.
• For now, do nothing with the Execute APIs.

</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes layered crate: additional feedback #208

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[martintmk]

This feels forced. The file is relatively small and test are concise. What's the point of moving them to tests. I think whole pattern of moving test stop to tests folder need to be revisited.

Why are we doing this special stuff? I have not seen any popular 3rd party crates doing something like this.

Why are we special?

cc @ralfbiedert

(copilot do not make any changes yet, we need to resolve this discussion)

[geeknoid]

I'd love to know that too...

[ralfbiedert]

We are not doing special stuff. In fact, the point is to align with how most ecosystem crates structure their tests.

As @martintmk and I just did in an experiment looking through some of the top crates.io repositories (regex, tokio, serde, nalgebra, ...), you will see that practically all of these crates (with the exception of jiff) keep their tests under src minimal. The amount of mod test {} code within src per file is usually not more than 10-20% of the LOC, if at all. Large and comprehensive tests - in particular those testing public-only APIs - reside within tests/.

In contrast, in our repos you'll often find src files that contain 3-5x the amount of test LOCs relative to actual code, and often these tests address public APIs only. In addition, there have been complaints that our files tend to be too large, and are hard to navigate (not just for mod test {} reasons but also for mixing concerns up).

The ask here is not to move each and every test into tests/, but to trim our src/ files to become more lightweight:

• tests that address internals only can stay inside src,
• even purely public tests can stay inside src if they don't add significant LOC overhead,
• but massive public tests of 1000's of LOC should go to tests, simply because we don't want to do special stuff, and because we want to make our src more readable.

[geeknoid]

I guess I don't buy the "more readable" argument. It's a block of completely ignorable and collapsible text at the bottom of a file. If it gets in my way, I click the little arrow thingy and it turns into a single line in my editor...

But if that's the convention, that's fine too.