search

WebAssembly / tool-conventions

Conventions supporting interoperatibility between tools working with WebAssembly.
Artistic License 2.0
297 stars 65 forks source link

Rename Code Annotations to Code Metadata #179

Closed yuri91 closed 2 years ago

yuri91 commented 2 years ago

In the process of rebasing the Branch Hinting proposal on top of the Custom Annotations proposal, I realized that the name "Code Annotations" is too confusing.

The term "annotation" is already used by the Custom Annotations proposal to refer to an analogous of sections in text format.

For example, the proposal adds a "Name annotation" corresponding to the "name section".

Adding Code Annotations to the mix makes it very confusing: A "Code Annotation section" would have its textual analogous named "Code Annotation annotation".

I propose to rename "Code Annotations" to "Code Metadata".

I feel it is a more descriptive name in itself, and it allows to have "Code Metadata sections" and "Code Metadata annotations" without any confusion.

We could consider just "Metadata", but I feel that it may be a too general term that could prevent other kinds of metadata being named as such in the future.

The section name in binary format would turn from code_annotation.<feature> to something like meta.code.<feature>. An alternative could be code.meta.<feature> or just meta.<feature> but I think it is nicer if the "meta" acts as a prefix for possible future kinds of metadata.

In the text format @code_annotation.<feature> would become @meta.code.<feature>.

I am interested in getting feedback about this, in particular from people that are currently experimenting with custom annotations.

As far as I know, other than the Branch Hinting proposal, only the Instrument and Tracing Technology proposal uses custom annotations (ping @jacob-abraham and @rrwinterton), and @tlively mentioned in a CG meeting that he wanted to experiment with a non-standard custom annotation in llvm.

tlively commented 2 years ago

Disambiguating names sounds reasonable to me. IMO code.meta.<feature> or meta.code.<feature> does not seem as descriptive as code_annotation.<feature>, though. Maybe it doesn't matter because <feature> will always be descriptive enough.

yuri91 commented 2 years ago

Do you think that also the name "Code Metadata" for the feature itself is less descriptive, or just the section/annotation strings?

Since the goal of this change would be to make the spec/explanation less confusing, I don't want to end up making things worse on that front.

tlively commented 2 years ago

I think "code metadata" is a good name. It even suggests to me that it is not supposed to have semantically observable affects on the code, which was less clear with "code annotations."

I think my concern would be resolved by using code.metadata.<feature> as the section name rather than trying to abbreviate it. meta by itself is somewhat ambiguous.

yuri91 commented 2 years ago

metadata instead of meta makes sense.

I would lean towards metadata.code.<feature> instead of code.metadata.<feature> though, because if in the future we will add new kinds of metadata and one wants to find all metadata sections, it is easier to search for a fixed prefix.

tlively commented 2 years ago

Sounds good to me!

yuri91 commented 2 years ago

I made a PR that changes the name.

I couldn't make a 1-1 translation because "metadata" is an uncountable noun.

So I added the concept of a "Code Metadata instance" to mirror a single "Code Annotation".

If this sounds weird, suggestions from native English speakers are welcome.

yuri91 commented 2 years ago

The feature is merged, I am closing the issue.