Re: [w3c/pointerlock] Editorial: Change the ref-name of the functions (#48)

> Convention through out this spec or across W3C specs? 

W3C.

>  Is that written somewhere so I can take a look and see how it generally applies?

Not explicitly, but you can see examples, for instance, in the TAG's API Design Guidelines:
https://w3ctag.github.io/design-principles/#live-vs-static

And also in the other specs created by the WG:
https://github.com/w3c/webappswg

(open any,  search for "()" to find methods)

> How does that apply to the functions with parameter? 

There are a number of different ways, depending on what you prefer. 

Payment Request defines the methods in a `h2`, then uses `<var>`, like so:

```HTML
<h2><dfn>show()</dfn></h2>
<p>
   The <code>show(optional <var data-type="Promise">detailsPromise</var>)</code> method MUST act as follows:
</p>
<ul class="algorithm">
    <!--- stuff -->
</ul>
``` 

What is neat about the above is that the type information propagates in the algorithm. 

Alternative,  if you ever need to just define a method inline with arguments: 

```HTML
<p>
   <dfn data-lt="requestPointerLock()">requestPointerLock(DOMString <var data-type="DOMString">someArg</var>)</dfn>
</p>
```

Eventually, plan on adding support support for function parameters to the `{{ }}` syntax too.


-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/pointerlock/pull/48#issuecomment-511631461

Received on Tuesday, 16 July 2019 01:45:20 UTC