From: Adam R. <ad...@ex...> - 2010-01-05 15:54:30
|
2010/1/5 Loren Cahlander <lor...@gm...>: > Hello Wolfgang, > > I think that we should create a strategy to move the java based function module documentation out into XQDoc files. I also think that the text within the description tag in XQDoc be allowed to contain DocBook style tags to format the text within the descriptions. Sounds sensible > This is now a lower priority, but should be discussed. > > Loren > > On Jun 10, 2009, at 03:43 PM, Wolfgang wrote: > >> Hi Loren, >> >> I agree with your suggestions, but would like to make an addition. We were actually thinking about moving away from embedding function documentation within the Java code. Some functions can be pretty hard to explain, but writing longer paragraphs in a Java string is just not possible. >> >> Ideally I would still like to keep the documentation together with the documented module, but as a separate XML document. Maybe a good compromise could be: we extend the current FunctionSignature and SequenceType to include variable names as suggested by Loren. >> >> However, as an alternative to providing a documentation string in the Java class, the developer can also specify an id which links into an XML document residing in the same package as the module. The XML document contains a list of function descriptors with a documentation element whose content is based on the docbook schema. The parameters could be described in the descriptor as well. >> >> The documentation generator could then combine the signature from the class with the description in the XML to create a self-contained output document. >> >> What do you think? >> >> Wolfgang > > > ------------------------------------------------------------------------------ > This SF.Net email is sponsored by the Verizon Developer Community > Take advantage of Verizon's best-in-class app development support > A streamlined, 14 day to market process makes app distribution fast and easy > Join now and get one step closer to millions of Verizon customers > http://p.sf.net/sfu/verizon-dev2dev > _______________________________________________ > Exist-development mailing list > Exi...@li... > https://lists.sourceforge.net/lists/listinfo/exist-development > -- Adam Retter eXist Developer { United Kingdom } ad...@ex... irc://irc.freenode.net/existdb |