A doc comment would be helpful, at least some examples.

A function name doesn't have to tell the whole story. The signature is enough to understand that this will return None for a device with no parent.

Oh yeah, I was kinda expecting some comment on this API, as I really struggled to name it properly. By bad, for not adding the rustdocs for it and hoping that a longer/detailed name would convey it properly.

So, I didn't name it just parent_xid because what's returned is not quite the parent_xid in all cases. For any child devices at level 2 and beyond, this function returns Some(<parent-xid>) as expected. But for the immediate child devices of the main device, where the parent xid is the device id of the main device, this function must return None instead of returning Some(<main-device-id>). We're returning None in that case, because all the existing SmartREST APIs like child_device_creation_message, service_creation_message_payload etc expects None when the message must be published to s/us directly and Some(<parent-xid>) when the message must be published to s/us/<parent-xid>. That's the reason why this function impl has this additional filtering step: filter(|tid| *tid != &self.device_topic_id) to switch it to None when the parent is the main device.

The alternatives were the following:

1. Implement a simple parent_xid function as suggested and call the additional filtering at the places where the SmartREST APIs are used.
2. Update those SmartREST APIs to take the main device xid as an additional parameter and do the filtering there

I implemented it this way it is now, to just have all that logic at one place and reuse it everywhere. But, if that API looks weird, then I can implement one of the above approaches.

PS: Writing so much to explain the API contract, I kinda feel that it was the wrong choice. Option. 2 above may have been a better choice.

I got it.

Option 2 sounds the correct choice (because moving away the c8y details under c8y_api).

However, it would be better to first stabilize the main PR and add such improvements only in a second step.

For now, simply add this note as a doc comment.

Resolved by 21c694f