I'm moving this over to the dev mailing lists, since I have a bunch of questions to the dev team:
1) The general need for a doctool It seems that there is no documentation generation tool available for LZX code as part of the OpenLaszlo platform. I know Webtop has some very basic documentation, which seems to be generated out of the LZX code. How does that work, and will that be part of the OpenLaszlo platform? If not, do you consider a platform with a custom language (LZX) complete - even if you don't provide up-to-date documentation tools? Do you plan to ship up-to-date documentation tools at all with a future releases? The Python script which is available is really simple. It generates simple HTML docs for any LZX class found in any LZX file in defined folders. And there's no official support for that tool. 2) The OpenLaszlo platform documentation vs. documenting custom LZX code Based on my research it appears that the documentation found at http://svn.openlaszlo.org/openlaszlo/trunk/docs/src is currently only used to document the OpenLaszlo LFC classes and component classes shipped with the platform. Has that documentation process ever been used to document custom LZX code, or even one of the demo apps? The stylesheet at http://svn.openlaszlo.org/openlaszlo/trunk/docs/src/xsl/lzx2js2doc.xsl(transforming LZX into j2sdoc format) is not fit to work with custom LZX applications, for some reasons: a) LZX component dependencies (<include href="lz/window.lzx" /> will cause the stylesheet to look for an 'lz' folder relative to the LZX file containing the include). b) Inclusion of a library path (<include href="someFolder" />) will cause the stylesheet to load the directory instead of the contained library.lzx file, causing an exception c) What if the LZX file contains a class written in JavaScript? It's not going to be documented. The lzx2js2doc.xsl transforms LZX into the jsdoc format ( http://wiki.openlaszlo.org/JS2Doc_Conversion). Does it make sense to use js2doc as intermediary format? 3) 3rd party solutions Maybe there's already an existing doctool within the community which could be published as open source. Are you aware of any solutions? Is anyone from the community willing to contribute code, or work on an implementation? There was LazDoc in 2005, but that's totally outdated by now: http://freshmeat.net/projects/lazdoc/ 4) What should be added to the docs? a) classes, attributes, events, methods b) class information (inheritance, mixins) c) stylesheets (internal/external, to give an overview of the styles defined for the app, and where that specific style information can be found) d) resources (list of static resources) What's missing here? How should runtime-specific switch-blocks be handled, where you have different implementations of a class depending on the runtime? Then, it would be good to have a doctool supporting different versions of LZX, since the language evolves so quickly. If you generate the docs, you should have a version switch '--version 4.9'. Many of the larger projects are still using older versions of OpenLaszlo. On Tue, Jan 11, 2011 at 10:08 AM, Raju Bitter < [email protected]> wrote: > The Python script is just scanning through defined lzdirs, picking up any > *.lzx file. I'm working on a RingoJS/Rhino based script now, source code > will be available at https://github.com/kamiJS/lzxdoctool in the next > days. > > > On Fri, Jan 7, 2011 at 11:48 PM, P T Withington <[email protected]> wrote: > >> Pretty sure that you just give it a file and it follows the <include>s in >> the file. That's how the components get documented. (And why they fail to >> show up when someone adds a component but does not add it to the relevant >> library.lzx so that the doc tool will find it.) >> >> Not a perfect mechanism by any means... >> >> On 2011-01-07, at 17:03, Raju Bitter wrote: >> >> > Which mechanism is used to identify all files which make up one >> application? >> > Does anyone know how I can point to one LZX file and generate a list of >> all >> > other LZX files I'd need to process? >> > >> > On Fri, Jan 7, 2011 at 10:39 PM, Raju Bitter < >> > [email protected]> wrote: >> > >> >> Thanks, Tucker. That's what I guessed, that we have to use the XSLT >> >> transformation. I'm currently looking at this page, let's see how far I >> get >> >> with that. >> >> http://www.openlaszlo.org/lps4.9/docs/developers/doc-toolchain.html >> >> >> >> >> >> On Fri, Jan 7, 2011 at 10:13 PM, P T Withington <[email protected]> wrote: >> >> >> >>> Our doc tool maintainer is on sabbatical (:-0). I was able to fix a >> bug >> >>> in the tools by reading the doc doc. It's pretty well written. >> >>> >> >>> Basically OL use a bunch of XSLT to walk over the LZX and output >> something >> >>> that docbook understands and then use docbook to create the final doc. >> >>> >> >>> I expect it would be reasonably easy to use the tools on your own LZX. >> >>> The complicated stuff is the bit that walks over the LFC JS and >> outputs >> >>> something that the LZX XSLT can parse... >> >>> >> >>> On 2011-01-07, at 16:05, Raju Bitter wrote: >> >>> >> >>>> Guess that means: no new tool available. Besides what's built into >> the >> >>> LPS >> >>>> for generating the OL docs. >> >>>> >> >>>> On Wed, Jan 5, 2011 at 8:33 PM, Raju Bitter < >> >>>> [email protected]> wrote: >> >>>> >> >>>>> What is the recommended tool for generating LZX documentation? The >> wiki >> >>>>> lists the following tools: >> >>>>> http://wiki.openlaszlo.org/Development_Tools#Documentation_Tools >> >>>>> >> >>>>> The page on the LzxdocTool has not been updated since 2007. Does >> that >> >>> still >> >>>>> work with the 4.8 version of OL? >> >>>>> http://wiki.openlaszlo.org/LzxdocTool >> >>>>> >> >>>>> - Raju >> >>>>> >> >>> >> >>> >> >> >> >> >
