Subject: DOCBOOK: Re: RFE #473365: Allow optional in funcprototype
Sorry for letting so much time go by, I tend to get behind, on these things. My apologies, if any of this stuff has changed, since 2.0.4 of TDG (though it does claim to accurately reflect DTD version 4.2). >From: Norman Walsh <firstname.lastname@example.org> >To: email@example.com >Subject: DOCBOOK: RFE #473365: Allow optional in funcprototype >Date: Tue, 21 May 2002 07:24:29 -0400 > > <funcprototype> > <funcdef>int <function>foo</function></funcdef> > <paramdef>int <parameter>bar</parameter></paramdef> > <optional> > <paramdef>int <parameter>baz</parameter></paramdef> > <paramdef>int <parameter>aaa</parameter></paramdef> > <optional> > <paramdef>int <parameter>bbb</parameter></paramdef> > <paramdef>int <parameter>ccc</parameter></paramdef> > </optional> > </optional> > </funcprototype> I hadn't yet an occasion to use 'funcprototype', but I'm glad to see that 'type' was recently added to 'paramdef'. However, isn't a 'funcparam' really a special-case of 'type'? Personally, I'm a bit unclear on why 'funcparam' even exists. And what about parameter defaults, such as in C++, XSLT, and Python? Shall I submit an RFE to add some sort of 'defaultval' element, which (ideally, with a cardinality of '?', if 'paramdef' weren't mixed) would also be included in the content model of 'paramdef'? Like 'type', 'defaultval' (or perhaps just 'default') should be a generic inline element, IMO. Personally, I can't see how the lack of a way to formalize default parameter values isn't a substantial deficiency, for people attempting to produce API documentation for languages with such a feature. It isn't really accurate to try to use 'replaceable', for this purpose (given it's current semantics (i.e. that of a meta-syntactic variable), as specified in TDG, anyhow). While I'm looking at the 'paramdef' content model, I can't help but wonder why it includes 'replaceable'. It's not necessarily inaccurate to describe a formal parameter name as replaceable, but it's also not as specific as calling it a parameter (with the connotation that one means "formal parameter", in the context of a funcprototype). Thanks for taking the time to consider my opinions. Please advise me as to whether I should proceed with submitting any RFEs. Sincerely, Matt Gruenke _________________________________________________________________ Get your FREE download of MSN Explorer at http://explorer.msn.com/intl.asp.
Powered by eList eXpress LLC