chore: adding @returns for provideOrchestration #9803
Conversation
| @@ -43,6 +43,8 @@ import { makeZoeTools } from './zoe-tools.js'; | |||
| * @param {Baggage} baggage | |||
| * @param {OrchestrationPowers} remotePowers | |||
| * @param {Marshaller} marshaller | |||
| * @returns {(facade: OrchestrationFacade, chainHub: ChainHub, vowTools: VowTools, zoeTools: ZoeTools, zone: Zone} ochestration | |||
There was a problem hiding this comment.
Why? This function is meant to return whatever it does so putting this here will require updating two places each time.
As motivation you referenced #9801 which says,
needed for clarity and documentation
Why?
There was a problem hiding this comment.
In general, many orchestration API lack @returns. Mine is a newbie (in blockchain and at Agoric) dev perspective, that I would be more confident using an API where return signature is clearly defined in docs, and I don't have to go through the code. Again, I am probably wrong, but this is how I see it.
On a side note, for my learning, what would be a potentially satisfactory answer to your why question?
There was a problem hiding this comment.
satisfactory answer
Something showing that the change is in fact needed for clarity and documentation. I assume we're talking about the docsite documentation and clarity for the reader of that.
I went to see how this changes provideOrchestration in its output but it's not in there at all. We need to export it in the top-level index.js.
There was a problem hiding this comment.
Since, provideOrchestration is to be marked @internal (relevant discussion in slack) there is no need for this PR, so I am closing this.
Deploying agoric-sdk with
|
| Latest commit: |
366a7be
|
| Status: | 🚫 Build failed. |
Adding a @returns tag for
provideOrchestrationAPIrefs:
#9801
#9757
Description
@dckc
I am adding a @returns tag for
provideOrchestrationAPI based on what I see in code - if something is wrong, please make suggestions.Security/Scaling/Documentation Considerations
None
Testing Considerations
Manual
Upgrade Considerations
May need to be updated if
provideOrchestrationchanges.