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 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: Digital signature URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20081006/9d92a04b/attachment.sig>
Hi Matthijs, On Oct 6, 2008, at 9:23 AM, Matthijs Kooijman wrote:> 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, - Devang
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. > > FixedThe 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) -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: Digital signature URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20081007/2d0c20cc/attachment.sig>