Jump to: navigation, search

Make any suggestions for modifications to this template here. Once it's complete, we can run a script to auto-generate most of the content of those articles that don't yet exist (anyone interested in writing that fairly simple script, leave a message here or contact me, otherwise I'll get around to it eventually) and manually update those that do. --Netocrat 20:15, 23 March 2006 (UTC)

Note "declaration" instead of "prototype" for non-functions

For objects, "prototype" makes no sense, so call the section "declaration" instead. Object-like macros can be treated as if they were real objects for this purpose (after all, we can't really tell that any given function isn't also a macro) - Even function-like macros that are necessarily macros should be treated as functions, for example, I'd use type va_arg(va_list args, typename type). In general, when documenting macro parameters, we should use 'pseudo-keywords' to document what they should be. I suggest: typename for names of types that need to be able to be followed with * to construct a pointer, e.g. for va_arg; struct_name for an argument that must be struct tag or a typedef which is a struct type, i.e. the argument to offsetof. scalar for expressions which must have a truth value, etc. Of course, the actual type for arguments which must be objects of a particular type, add the pseudo-keyword "lvalue" for arguments which must be an lvalue. Should there be a pseudo-keyword for arguments that may be evaluated more than once, or should we just note that in the description? --Random832 20:44, 23 March 2006 (UTC)

I tried to avoid/delay this issue by titling the article "Standard library /function/ template", so if we're going to generalise it let's move it to "Standard library component template" (there'll be other slight changes in that case e.g. not all reference links will work for all non-functions). "Declaration" can't be applied to function-like macros as far as I can see from the Standard's wording - let's use "synopsis" instead as the Standard uses or differentiate based on meta-type. The rest of your suggestions seem OK unless I'm missing a hidden catch - we'd need to have the syntax highlighter link them to a descriptive article which is do-able. I've started a Planning:Standard symbol list page incorporating some content from User:Random832/Multi_pages which we can fill out first and get an idea of whether we're missing anything. --Netocrat 08:11, 29 March 2006 (BST)
Personal tools