defineElement is another name that seems to be popular on the thread (and discussion is ongoing).

It seems more clear to me, and is not really parallel to registerProtocolHandler. The parallel version would be something like registerElementHandler or registerElementDefinition, but defineElement conveys the same idea more concisely.

https://github.com/w3c/webcomponents/commit/14d393e00f1ede55dae2e2dc245a2d594e739c46

Played with both. registerElement fit a bit better with the rest of the narrative.

Reopening to reconsider defineElement.

I gave a bunch of rationale on the list for why defineElement was better than registerElement:
http://lists.w3.org/Archives/Public/public-webapps/2013OctDec/1026.html

Many people agreed, including Dominic from Google:
http://lists.w3.org/Archives/Public/public-webapps/2013OctDec/1032.html

The only rationale you gave for registerElement instead is this:
> Played with both. registerElement fit a bit better with the rest of the narrative.

Can you please either adopt defineElement or give some substantive reasoning for why my arguments are wrong? I don't find "played with both" or "fit better with the rest of the narrative" very convincing.

(In reply to Dominic Cooney from comment #0)
> Based on the thread starting here:
> <http://lists.w3.org/Archives/Public/public-webapps/2013OctDec/0968.html>,
> document.register should be renamed to document.registerElement. It's more
> specific about what this method does, lines up with other "register" methods
> (eg registerProtocolHandler)

I don't think we should line the name up with registerProtocolHandler. As far as I understand, registerProtocolHandler permanently associates a URL with a given protocol. The registration doesn't go away simply because the page that made it got closed. In comparison, custom elements are NOT persistent across sessions.

> Retains an imperative flavor (since it may trigger callbacks.)

I don't know why "register" is considered more imperative than "define". Both of them are verbs.

I'm sorry there wasn't more clarity on the arguments. The rationale for 'register' goes something like this:

There was a first concept from the originators of Custom Elements, which was to make 'a way to attach a JS class to a element'. So, the vision has been toward:

  class MyElement extends HTMLElement {
    ...
  }
  document.registerElement('my-element', MyElement);

From this point of view, the `class` statement is what I would consider the definition. From there, it seemed clear that the document method was registering a tag-name for that. I believe this is also fairly close to what I expect to happen in implementations, which is to say an entry is being added to a registry. That resonance helped me, for one, to argue for `registerElement`.

Appendix: this is close as we come today to the above `class` construction:

MyElement = function() {
};
MyElement.prototype = Object.create(HTMLElement.prototype, {
  ...
});
MyElement.prototype.createdCallback = MyElement;
MyElement = document.registerElement('my-element', MyElement);

(In reply to Scott Miles from comment #5)
> I'm sorry there wasn't more clarity on the arguments. The rationale for
> 'register' goes something like this:
> 
> There was a first concept from the originators of Custom Elements, which was
> to make 'a way to attach a JS class to a element'. So, the vision has been
> toward:
> 
>   class MyElement extends HTMLElement {
>     ...
>   }
>   document.registerElement('my-element', MyElement);
> 
> From this point of view, the `class` statement is what I would consider the
> definition. From there, it seemed clear that the document method was
> registering a tag-name for that.

I don't understand this given we can't really define an element without a name. We don' refer to an element with its IDL interface name. See http://www.w3.org/html/wg/drafts/html/CR/dom.html#elements

Look at the very first sentence of this section:
"Elements, attributes, and attribute values in HTML are defined (by this specification) to have certain meanings (semantics). For example, the ol element represents an ordered list, and the lang attribute represents the language of the content."

Here, we mention "ol" element, not HTMLOListElement.

In addition, multiple elements can share a single IDL interface; e.g. del and ins element share single HTMLModElement. In that sense, defining an element is synonymous to defining a tag name.

(In reply to Maciej Stachowiak from comment #3)
> Reopening to reconsider defineElement.

Please don't rename the bug that already has a commit on it. Makes difficult to figure out what's happening.

> 
> I gave a bunch of rationale on the list for why defineElement was better
> than registerElement:
> http://lists.w3.org/Archives/Public/public-webapps/2013OctDec/1026.html
> 
> Many people agreed, including Dominic from Google:
> http://lists.w3.org/Archives/Public/public-webapps/2013OctDec/1032.html
> 
> The only rationale you gave for registerElement instead is this:
> > Played with both. registerElement fit a bit better with the rest of the narrative.
> 
> Can you please either adopt defineElement or give some substantive reasoning
> for why my arguments are wrong? I don't find "played with both" or "fit
> better with the rest of the narrative" very convincing.

The "element registration is a process of adding an element definition to a registry": http://w3c.github.io/webcomponents/spec/custom/#dfn-element-registration 

On the other hand, "Defining an element" (or defineElement) would be the act of constructing a definition, which doesn't quite hit the spot.

(In reply to Scott Miles from comment #5)
> I'm sorry there wasn't more clarity on the arguments. The rationale for
> 'register' goes something like this:
> 
> There was a first concept from the originators of Custom Elements, which was
> to make 'a way to attach a JS class to a element'. So, the vision has been
> toward:
> 
>   class MyElement extends HTMLElement {
>     ...
>   }
>   document.registerElement('my-element', MyElement);
> 
> From this point of view, the `class` statement is what I would consider the
> definition. From there, it seemed clear that the document method was
> registering a tag-name for that. I believe this is also fairly close to what
> I expect to happen in implementations, which is to say an entry is being
> added to a registry. That resonance helped me, for one, to argue for
> `registerElement`.
> 
> Appendix: this is close as we come today to the above `class` construction:
> 
> MyElement = function() {
> };
> MyElement.prototype = Object.create(HTMLElement.prototype, {
>   ...
> });
> MyElement.prototype.createdCallback = MyElement;
> MyElement = document.registerElement('my-element', MyElement);

First, I don't think this addresses my arguments for why defineElement is better:
<http://lists.w3.org/Archives/Public/public-webapps/2013OctDec/1026.html>. Specifically, it really sounds like registerElement would take a specific element, not a prototype that defines a whole kind of element.

I agree with you that a class definition defines a class. However, associating a tag name with a class is what defines the element (the element being a particular tag name).

(In reply to Dimitri Glazkov from comment #7)
> (In reply to Maciej Stachowiak from comment #3)
> > Reopening to reconsider defineElement.
> 
> Please don't rename the bug that already has a commit on it. Makes difficult
> to figure out what's happening.

What do you think is the correct process if I disagree with the way in which a bug was resolved, or think it has inadequate rationale? It seems like reopening it without renaming would be confusing, and filing a new bug would also be confusing. But I'm happy to follow whichever is the preferred process.

> 
> The "element registration is a process of adding an element definition to a
> registry":
> http://w3c.github.io/webcomponents/spec/custom/#dfn-element-registration 
> 
> On the other hand, "Defining an element" (or defineElement) would be the act
> of constructing a definition, which doesn't quite hit the spot.

Two counters:

(1) "Registry" is not a user-exposed concept. A component implementor should not have to think about the fact that the implementation may internally have a registry. API names should not expose purely internal concepts.

(2) Let's say you have a definition for a word in English. You want to add that definition to a dictionary. We would tend call that "defining a word", not "registering a word definition" in normal English. In other words, "define" is the verb that means "associate a definition with the term it defines". It is true that a definition can exist in free-standing form, without yet being bound to a term. But at that point it's not defining anything yet.

Maybe we should take this back to public-webapps? I wish you had commented on the original thread that you disagreed with the arguments given for defineElement. It is dispiriting to give detailed feedback and then have a bug resolved without directly addressing it.

> Let's say you have a definition for a word in English. You want to add that definition to a dictionary. We would tend call that "defining a word".

You started by positing a definition, and then called the thing you did with it 'defining'. Dictionaries do not create definitions, they only record them.

(In reply to Scott Miles from comment #10)
> > Let's say you have a definition for a word in English. You want to add that definition to a dictionary. We would tend call that "defining a word".
> 
> You started by positing a definition, and then called the thing you did with
> it 'defining'. Dictionaries do not create definitions, they only record them.

Yes, 'defining' is the thing you do with a definition when you associate it with a term. (Note that a free-floating definition with no term has not defined anything.) 

A registry or dictionary would be a place where you might record the associations of definitions with terms. Making that association is the act of defining.

To bring this back to custom elements, a class that implements a custom element may be a definition, but it does not "define" until you associate it with a term, namely the custom element name.

I believe this is consistent with the naming I'm proposing.

Updating title to reflect remaining suggestion.

Moved to https://github.com/w3c/webcomponents/issues/140