[pdata] Add documentation defining naming conventions

[dmitryax]

The documentation is intended to summarize all the naming rules followed in pdata module

[codecov]

Codecov Report

Base: 92.48% // Head: 92.48% // No change to project coverage 👍

Coverage data is based on head (aeccca5) compared to base (806ba4c).
Patch has no changes to coverable lines.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6255   +/-   ##
=======================================
  Coverage   92.48%   92.48%           
=======================================
  Files         218      218           
  Lines       13124    13124           
=======================================
  Hits        12138    12138           
  Misses        769      769           
  Partials      217      217           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[dmitryax]

@open-telemetry/collector-approvers PTAL

[tigrannajaryan]

I think it is useful to document the design principles of pdata API, but I think it would be beneficial to remove from this document the parts which are already codified in the pdata generator to avoid the need to maintain the document if the generator is changed in any way.

[tigrannajaryan]

Would it be better to delete all these lines and only keep one exception example, to reduce the amount of maintenance this document requires if the source code is refactored? Let the source code be the source of truth. If you want the fact of the exception to be documented it would be better to add a comment in the source code near the name.

[dmitryax]

Makes sense. Removed

[bogdandrutu]

Please document all exceptions, see comment
#6283 (comment)

[dmitryax]

Please document all exceptions, see comment #6283 (comment)

We had the struct name exceptions listed in this document initially.

@tigrannajaryan suggested to not list them all, but use the code as source of truth #6255 (comment).

If we want to document field name exceptions, I believe we should do the same for the structs. So the question is where we document the exceptions: source code comments or this Readme file.

Using the readme adds maintenance burden as Tigran pointed out. But I don't like putting them into the comments because the comments are intended for API users who probably don't care why particular type or field is called one way or another. So I would rather list them here, and I don't think it'll be a lot of them going forward to bother us with keeping it in sync.

[dmitryax]

@bogdandrutu, I mentioned all the naming exceptions in this doc

[bogdandrutu]

Not perfect, but a great start :) Thanks @dmitryax