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>
On Oct 7, 2008, at 3:12 AM, Matthijs Kooijman wrote:> 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. - Devang
Hi Devang, On the risk of becoming a nag, I have two more points :-)> 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 -------------- 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/d306c6a5/attachment.sig>