#Module docs
static pilot
The problem is they're not the same thing. We need to figure out what the convention should be and stick to it. I mean shell, call, daggerverse, cloud, etc... What you see in shell was my best guess but sometimes I'm not sure. Especially because without the convention, some modules may do it one way, others another, and we want to show useful stuff in our clients.
I have the same issue in Python where the module doc is in __init__.py (which is the entrypoint of the package), but the main object is in main.py. I've been thinking about adding support for specifying the module doc in the same file where the main object is (so if not in __init__.py the SDK would look in main.py as a fallback).
I don't want to remove support from __init__.py because it makes sense from the Python package POV, but I also see the benefit of keeping it in the same file as the main object for maintainability.
But I wouldn't replace the main object doc with the module doc, unless there's a consensus to make them the same and apply it everywhere. Maybe @manic swallow, @olive maple or others already think of them as the same. I haven't, but I don't dislike it, however I may also be forgetting some use cases where they're better as separate "things".
safe niche
The thing I discover is as I have both the module and object desc, only the object one is visible, at least from shell perspective. But yeah, maybe that's just something we need to clarify and update more widely. I'll change nothing on Java side before we agree then.
static pilot
Indeed since https://github.com/dagger/dagger/pull/9897 .help . prefers the main object's description but that may have come from some discussion I don't remember about.
The original intention was that .help . showed the module's docstring and constructor docstring, while . | .help showed the main object's docstring.
That's because it's consistent with other objects. The latter example documents the return type of a function, which for the constructor is the main object.
Ok, I tracked it to this response: #p-shell message
Looking at that convo again, it's not exactly clear which one should be the fallback of the other. Atm I think .help . should prefer the module doc and fallback to the main object doc, not the other way around.
if you have both you can get the main object's doc specifically with . | .help or .help <MainObjectName>, but the module description will never be shown currently.
Only the first line is displayed on the list in .help.