doc: Fix and expand design.md

[ViniciusCestarii]

Improve two points on design.md:

• Clarify that only ProxyClient is directly exposed to users and meant to be used directly and inherits from the C++ interface class so it can be used as a pointer to it.
• Document the special destroy capnp method, which handles synchronous server-side object destruction.

[DrahtBot]

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	ryanofsky

If your review is incorrectly listed, please copy-paste <!--meta-tag:bot-skip--> into the comment that the bot should ignore.

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #287 (Split repository into master (library source) and support (CI, docs, examples) branches. by ryanofsky)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

[ryanofsky]

Code review 6314aa1. Nice catches calling out two special cases that don't match the more general descriptions in the design doc.

I think the changes should be edited a little more for clarify, though, so left some suggestions below to consider

[ryanofsky]

In commit "doc: Fix and expand design.md" (6314aa1)

Nice catch. Current text is inaccurate in claiming the ProxyClient type is not exposed at all, because the pointer returned to the initial remote object returned by ConnectStream is a ProxyClient<InitInterface> object. But this object isn't really meant to do anything other than inherit from InitInterface and implement its methods. So I think potentially ConnectStream could be changed to return an InitInterface pointer instead of a ProxyClient<InitInterface> and it wouldn't affect anything.

All other remote objects obtained by calling InitInterface methods will be ProxyClient<Foo> objects, but only exposed to user code as Foo pointers, so that aligns with current documentation. Current documentation should be mostly accurate except for the ConnectStream exception, and it is misleading to change it to say ProxyClient generated class meant to be is exposed and used more directly.

LLM suggests following which I think would be more accurate:

The ProxyServer generated class is not directly exposed to the user. The ProxyClient generated class inherits from the C++ interface class, so user code interacts with it through the abstract interface type — the ProxyClient type itself is generally not visible or accessible without a cast. ConnectStream returns a unique_ptr<ProxyClient<InitInterface>> as an exception for the root Init interface, but even there users typically treat it as a pointer to the abstract InitInterface. For all interfaces returned by Init methods (e.g., Printer, Calculator), the return type is the abstract class pointer, hiding the underlying ProxyClient entirely.

[ViniciusCestarii]

I agree, I wanted to make it not misleading but added another misleading

Fixed on (used your suggestion with a tweak: replaced the em dash with ", and"): 18db0ab

[ryanofsky]

In commit "doc: Fix and expand design.md" (6314aa1)

This is worth mentioning, but placement is awkward since it is interrupting the description of the flow for server method calls by describing a special case before the general case is described and shown in the diagram.

Would suggest moving the new paragraph after the mermaid diagram and tweaking text to connect it to previously described flow. LLM suggests following which I think is an improvement:

Destroy methods are a special case: a capnp interface can declare a destroy method that is handled by ServerDestroy instead of ServerCall. Rather than dispatching through the ServerField/ServerRet/ServerCall chain to a C++ interface method, ServerDestroy calls invokeDestroy() on the ProxyServer, which resets m_impl and runs any registered cleanup functions, giving the client a way to synchronously destroy the wrapped object on the server side.

[ViniciusCestarii]

I agree

Fixed on: 18db0ab

[ViniciusCestarii]

Forced-push 18db0ab to add suggested changes

[ryanofsky]

Code review ACK 18db0ab. Thanks for the fixes and for taking suggestions!

[ryanofsky]

In commit "doc: Fix and expand design.md" (18db0ab)

This all looks accurate now. But I feel like it is also more confusing. The point this is trying to make is that library users don't really interact with the ProxyClient and ProxyClient classes directly. Library users define virtual interfaces and call interface methods that ProxyClient classes implement. And they provide interface pointers that ProxyServer classes wrap. They can create a ProxyClient object accessing an interface by calling ConnectStream, and they can create a ProxyServer object wrapping an interface by calling ConnectStream. The interface type is passed to ConnectStream and ServeStream as a template parameter, and Connect/Serve functions are typically only called once with an initial interface or InitInterface type. From there, InitInterface methods can return pointers new interfaces, causing new ProxyClient and ProxyServer objects to be created when they are called, and those interface and create and pass around pointers to other interface.

I think maybe it might make sense to structure the paragraph more like that description but I don't have a clear suggestion.

This change is probably better than the status quo since it is more technically accurate though, and it seems fine to follow up on improving this later.

[ViniciusCestarii]

I agree. This revised version is more accurate, but it may also be harder to follow. Thanks for the feedback