On 14 May 2010 14:58, Hannes Magnusson <hannes.magnus...@gmail.com> wrote: > On Fri, May 14, 2010 at 15:31, Richard Quadling > <rquadl...@googlemail.com> wrote: >> On 14 May 2010 13:40, Hannes Magnusson <hannes.magnus...@gmail.com> wrote: >>> On Thu, May 13, 2010 at 15:00, Richard Quadling >>> <rquadl...@googlemail.com> wrote: >>>> So, I would like to use a role on the methodsynopsis to indicate OOP >>>> or PROC use. This will allow me to include only the OOP methodsynopsis >>>> via the xinclude in the event of method overloading. >>>> >>>> Changing >>>> >>>> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) >>>> xpointer(id('class.xyz')/db:refentry/db:refsec...@role='description']/descendant::db:methodsynopsis[1])" >>>> /> >>>> >>>> to >>>> >>>> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) >>>> xpointer(id('class.xyz')/db:refentry/db:refsec...@role='description']/descendant::db:constructorsynopsis)" >>>> /> >>>> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) >>>> xpointer(id('class.xyz')/db:refentry/db:refsec...@role='description']/descendant::db:destructorsynopsis)" >>>> /> >>>> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) >>>> xpointer(id('class.xyz')/db:refentry/db:refsec...@role='description']/descendant::db:methodsynops...@role='oop'])" >>>> /> >>>> >>> >>> I like it. >>> >>> It has always bothered me that functions use <methodsynopsis>. In the >>> beginning it was <funcsynopsis>, but I can't find any discussion on >>> why it was changed. The <funcdef> model does fit well for us.. But >>> like you said, that would be a major change. >>> >>> -Hannes >>> >> >> Thank you Hannes for the feedback. >> >> I've got change for this which I'm just finalising. >> >> It should mean that we don't need to add role="oop" to all the >> methods, only role="procedural" to the procedural >> methodsysonpsis/constructorsynopsis/destructorsynopsis, so less work >> for the translators. > > Since that line isn't translated you could update all the translations > and everything in one go.. > It would probably even work to svn diff en > role.patch && cd ja && > patch -p1 < ../role.patch ...... > >
Aha! That's good. >> Essentially >> >> xxxsynopsis[not(@role='procedural')] >> >> says exclude where the role = procedural. This allows through those >> with no role and those that may now be 'oop' due to my last commit. > > What is the default value of role then? > I'd prefer to be consistent throughout.. > Either all methods use role=oop or all functions use role=procedural.. > > That also makes it simpler to work with during rendering if we ever want to. Due to my own movable goal posts, I wasn't really sure what to end up with. If role="oop" is wanted, even if no procedural interface, then that's fine. It does keep things consistent and that makes me happy. I'll go with that. >> And for excluding private inherited methods.... >> >> methodsynopsis[not(@role='procedural') and not(modifier='private')] > > I thought we removed private things already? > They make no sense for the end user, he can't do anything with it and > it doesn't affect him in any way. It is an issue if the <modifier>private</modifier> is also <modifier>final</modifier> The __clone() method (for example) in Exception. But, considering that a bit more... I think all <modifier>final</modifier> methods need to be documented as something like ... /* The following methods have been declared as final and private in a sub class and cannot be overloaded in this class or in a sub-class of this class. */ sort of thing which would be accessible to xinclude by ... xxxxsynopsis[(modifier='final') and (modifier='private')] Some suitable styling would need to be made for this. > > > > >> >> <xi:fallback /> >> >> would also be enough to allow for a standard way to include the class >> methods without worrying about if they exist (which is what I'm >> currently leaving it as so the output is the same). >> > > Sounds reasonable. > Make it as little work as possible to create classreference pages, it > should be possible to copy&paste it all without thinking about the > xincldues :] > > -Hanens > -- ----- Richard Quadling "Standing on the shoulders of some very clever giants!" EE : http://www.experts-exchange.com/M_248814.html EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 ZOPA : http://uk.zopa.com/member/RQuadling
