(Function) attributes documentation

Hi all,

due to the recent changes regarding paramater/function/return type attributes,
I think the documentation around that could use some improvement. In
particular, I see the following problems:
* The section "Functions" in the LangRef has a large textual description
   about how it should look, but no definition of syntax, or even a few
   examples of the syntax. This makes it very hard to read.
* The section "Functions" only mentions return value attributes and parameter
   attributes, but not function attributes.
* The section about the call and invoke instructions do not mention any
   attributes at all.
* The section about parameter attributes is a bit unclear as to what are
   valid return attributes and what are valid parameter attributes. From the
   code, only zeroext, signext and inreg are valid for return values, but
   adding an explicit "This is not a valid attribute for return values" to the
   others would make this a lot clearer.

These problems seem to have been around for some time, but I guess it would be
good to fix them (but I won't be having the time for it, unfortunately).

Gr.

Matthijs

Hi Matthijs,

Hi all,

due to the recent changes regarding paramater/function/return type attributes,
I think the documentation around that could use some improvement. In
particular, I see the following problems:
* The section "Functions" in the LangRef has a large textual description
  about how it should look, but no definition of syntax, or even a few
   examples of the syntax. This makes it very hard to read.

This description provides links for each item. Do you think we need an example here?

* The section "Functions" only mentions return value attributes and parameter
  attributes, but not function attributes.

Fixed

* The section about the call and invoke instructions do not mention any
  attributes at all.

Fixed

* The section about parameter attributes is a bit unclear as to what are
  valid return attributes and what are valid parameter attributes. From the
   code, only zeroext, signext and inreg are valid for return values, but
   adding an explicit "This is not a valid attribute for return values" to the
   others would make this a lot clearer.

Fixed

These problems seem to have been around for some time, but I guess it would be
good to fix them (but I won't be having the time for it, unfortunately).

Let me know, if the docs are clear now or if we can improve them.
Thanks,

Hi Devang,

the improvements you made are good, I think the docs are a lot clearer now. I
stil have a few more points, though.

> * The section "Functions" in the LangRef has a large textual description
> about how it should look, but no definition of syntax, or even a few
> examples of the syntax. This makes it very hard to read.

This description provides links for each item. Do you think we need an
example here?

I would add a syntax "specification", just as with the "alias" section below.
This makes it a lot easier to look up something. In addition, it would not
hurt to include one or two actual examples as well.

> * The section about the call and invoke instructions do not mention any
> attributes at all.

Fixed

The description now mentions function attributes, but the syntax spec doesn't.

Additionally, the description uses "function args", whereas the syntax spec uses
"param list". I think that using "arguments" is more correct than "parameters"
for the call instruction [1], though the source (llvmParser.y) also uses these
the wrong way around AFAICS.

This argument list is not so well specified, however. In particular, it is not
so clear if you are allowed (or required?) to specify parameter attributes in
the call instruction. From the parser and the examples I can see that it is
allowed, but I'm rather curious for the semantics here. Can they override
attributes on a declaration, or augment them, or?

These points are again for the call and invoke instructions.

Gr.

Matthijs

[1]: http://en.wikipedia.org/wiki/Parameter_(computer_science)

Hi Devang,

the improvements you made are good, I think the docs are a lot clearer now. I
stil have a few more points, though.

* The section "Functions" in the LangRef has a large textual description
about how it should look, but no definition of syntax, or even a few
examples of the syntax. This makes it very hard to read.

This description provides links for each item. Do you think we need an
example here?

I would add a syntax "specification", just as with the "alias" section below.
This makes it a lot easier to look up something. In addition, it would not
hurt to include one or two actual examples as well.

I added syntax spec.

* The section about the call and invoke instructions do not mention any
attributes at all.

Fixed

The description now mentions function attributes, but the syntax spec doesn't.

fixed. fixed broken link also

Additionally, the description uses "function args", whereas the syntax spec uses
"param list". I think that using "arguments" is more correct than "parameters"
for the call instruction [1], though the source (llvmParser.y) also uses these
the wrong way around AFAICS.

done.

This argument list is not so well specified, however. In particular, it is not
so clear if you are allowed (or required?) to specify parameter attributes in
the call instruction. From the parser and the examples I can see that it is
allowed, but I'm rather curious for the semantics here. Can they override
attributes on a declaration, or augment them, or?

This is true for ret attribute as well as function attributes. As I understand, it depends on the attribute itself. Each attributes doc, pointed by a link, should clarify this.

Hi Devang,

On the risk of becoming a nag, I have two more points :slight_smile:

I added syntax spec.

Could you also include a line for the declare keyword, in addition to the
define keyword?

Also, the text says there is a return type and then the param attr for it,
while the syntax shows them the other way around. Which one is it?

This is true for ret attribute as well as function attributes. As I
understand, it depends on the attribute itself. Each attributes doc,
pointed by a link, should clarify this.

Somebody should probably have a look through the code to document what is
defined by it already...

Gr.

Matthijs