Complete editorial overhaul of usubscription.proto#323
Conversation
sophokles73
left a comment
sophokles73
left a comment
There was a problem hiding this comment.
In general, I do not think that it is a good idea to put all the effort for documenting the service interface into the proto3 file. FMPOV we should define the service in the specification document using appropriate means, e.g. UML and textual description.
The proto3 file is simply a representation of it that can be fed into a protoc compiler...
I was thinking that too - but this means we'd simply remove all the docs from the proto file (and backsync with the textual spec where necessary). Should we? (remove the docs from proto) |
IMHO we shouldn't remove all comments altogether but instead strip them down to the bare minimum, adding pointers to the specification document for reference. @PLeVasseur @stevenhartley WDYT? |
|
I was wondering whether to simply use requirement links back to the textual spec... |
You mean OpenFastTrace spec items? |
|
Yes, I was thinking OFT dsn items, linking back to the corresponding req items in the text. That way, the text spec formally becomes the source of truth, and can be implemented/dsn-detailed by any specific technology in the future (should we ever move away from proto, for instance). |
sophokles73
left a comment
sophokles73
left a comment
There was a problem hiding this comment.
FMPOV the complete service USubscription should be removed from the proto file because we only need the message definitions when we use AsyncAPI for defining the service interface ...
| // [.specitem,oft-sid="dsn~usubscription-subscribe-protobuf~1",oft-needs="impl,utest"] | ||
| // The uSubscription service `Subscribe()` function *MUST* implement the corresponding protobuf definition in {usubscription_proto_link}. |
There was a problem hiding this comment.
| // [.specitem,oft-sid="dsn~usubscription-subscribe-protobuf~1",oft-needs="impl,utest"] | |
| // The uSubscription service `Subscribe()` function *MUST* implement the corresponding protobuf definition in {usubscription_proto_link}. |
There was a problem hiding this comment.
This one I left in as a marker for this question: do we want to reference the asnycapi defitinition here?
Because there is nothing fundamentally new/additional contained in the asyncapi spec, it's just a more formalized version of the definitions in the README.
Yes this will go - I left in in for now, as I step-by-step remove the service definitions. Once these are all gone, the entire section will go. |
| * is not a valid {uuri_ref} or | ||
| * contains a _wildcard_ authority or | ||
| * contains a _wildcard_ uEntity ID (`ue_id`) or | ||
| // * contains a _wildcard_ resource ID, |
There was a problem hiding this comment.
Is this commented out by mistake?
|
|
||
| * is not a valid {uuri_ref} or | ||
| * contains a _wildcard_ authority or | ||
| * contains a _wildcard_ uEntity ID (`ue_id`) or |
There was a problem hiding this comment.
Can I subscribe to up://vehicle/FFFFA1B0/8001?
|
Due to massive changes on all levels of the usubscription API resulting from this rework, this will become a new v4 API instead of a evolution of the current v3. |
2 participants
Update, improve and cleanup comments and documentation of usubscription.proto
This is a complete once-over of almost every doc-string in the usubscription protobuf definition, and the first part of the work to address #321