On Thu, Jun 12, 2025 at 10:44 AM shveta malik <shveta.ma...@gmail.com> wrote: > > On Thu, Jun 12, 2025 at 4:13 AM Peter Smith <smithpb2...@gmail.com> wrote: > > > > Phrases like "... it is recommended..." and "... intended for testing > > and debugging .. " and "... should be used with caution." and "... it > > is advisable to..." seem like indicators that parts of the above > > description should be using SGML markup such as <caution> or <warning> > > or <note> instead of just plain text. > > > > I feel WARNING and CAUTION markups could be a little strong for the > concerned case. Such markups are generally used when there is a > side-effect involved with the usage. But in our case, there is no such > side-effect with the API. At max it may fail without harming the > system and will succeed in the next invocation. But I also feel that > such sections catch user attention. Thus if needed, we can have a NOTE > section to convey the recommended way of slot synchronization. >
I think NOTE is fine for API in this case, but we can mention that the API is more prone to get the synchronization failure message, as you have shown in the patch. It would also be better to briefly explain in user terms why the API is more prone to such a failure. -- With Regards, Amit Kapila.
