From OpenLaszlo
- Specifications for OpenLaszlo 4.1, Documentation Tools December Deliverable (11.1.2007 revision)
- The content of the 4.1 docs should match the 3.4 docs, to the extent that the underlying APIs match. The exact requirements for matching content is listed at wiki.openlaszlo.org—Doctools_QA_Specs <http://wiki.openlaszlo.org/Doctools_QA_Specs>
- Handling Departures from 3.4:
- Noticeable changes to layout and formatting need to be approved by John, Antun, or David Temkin.
- Departures in content should be identified by QA then reviewed by the toolsmith.
- Items not listed in the 3.4 reference are presumed to be private. Without consulting the API quorum, the toolsmith will mark such methods/attributes/events private in the source with js2doc comments.
- Departures other than items-that-should-be-marked-private (1.2.2.1) are either API changes or bugs. These must be reviewed by the API quorum. If the API quorum approves the changed api, the developer responsible for that code will make the js2doc comments match the new api. If the API quorum does not approve the change, the toolsmith will mark that API private.
- If the departure is due to an error in the tools, the toolsmith will fix the tools. This class of error should be identified early by QA and the toolsmith in concert.
- Do not document or list methods marked private.
- APIs available only in swf will be listed and marked with a simple annotation, "swf only."
- The content in hardpages and wrappers from 3.4 must be present in 4.1.
- Navigation
- Include complete left-nav as swf-only lzx app
- Also include html-only, non-dynamic index.
- Plan of Attack
- This project requires both significant tools work and significant content work. The order of attack will be as follows:
- Bring tools to working properly as defined below for classes that are perfectly documented, and to at least survive generating documentation for less-ideally-documented classes.
- Find and repair missing hardpages.
- Identify (QA) and correct (toolsmith) dissimilarities and obvious errors in groups of classes and tags in order of their visiblity to application developers. This approach will ensure that as the delivery date approaches, the most important areas of the reference are in the best shape. (The toolsmith will consult Antun to make sure that this order is a reasonable reflection of application developers use of the reference.)
- Totally core classes
- node, view, canvas, text
- datapath, datapointer, other core data types
- layout, simplelayout
- (TBD Antun)
- Most-commonly-used components
- button and button flavors, combobox, menu, context menu, edittext, slider
- (TBD Antun)
- Commonly used non-component classes, tags, services, etc
- state, method, event, attribute, script
- html, browser
- LzFocus, LzSelectionManager
- New data APIs (These will be surveyed early, then examined and corrected when the doc content guy says they are ready for review.)
- Base components
- Extensions
- Incubator
- Live examples are important, but secondary to the content of the reference API. Live example support will be verified and repaired where necessary in this order:
- Developers Guide live examples before Reference Guide live examples
- Deployment to labs before installable distros before source builds
- Attributes List
- The structure of the attributes list will change. The Usage column will disappear. The Category column will now offer three possible values, of which exactly one applies to each attribute:
- read/write
- For attributes in this category, you can use foo.setAttribute(myattr) and you can read it with foo.myattr. Most attributes are in this category. Documentation for this category will include something to the effect of "dont do foo.myAttr = bar" and a link to the cautionary notes in the Developers Guide.
- read-only
- These are externally visible indicators of internal state. They cannot be set, not even at initialization, nor in the tag. For instance: LzNode.isinited, LzView.framesloadratio, LzDataNode.nodeType, LzDataElement.childodes, LzReplication.clones, LzState.isapplied
- These should be tagged in the code as @modifiers readonly
- initialize-only
- Must be set at initialization time, whether by tag or by "new Foo( par, {myattr: "cheese"})". These attributes may be read at runtime with foo.myattr. Caveat in strong language: it is an error to set these at runtime. Link to the cautionary/explanatory note in the Developers Guide.
- These should be tagged in the source as @modifiers final
- special
- An odd catch-all for weird cases. There are just a few of these: canvas.debug is one, because you cant even read it at runtime. Each "special" attribute should have a comment describing whats special about it.
- These should be tagged in the code as @modifiers special
- Events will be listed in events list, not in the attributes list, with the exception of attribute handlers, which will be listed in the attributes list as read/write.
- Methods list should list the same information as in 3.4
- Special setters like setText() are to be considered deprecated. They will appear in the reference along with the other methods of the appropriate class, but they will be marked deprecated. The developers guide will explain why we are recommending that they be replaced with setAttribute.
- Some things that look like special setters are actually important APIs that should indeed be public. In some cases, like setSource vs setResource, the naming scheme of the setters doesnt match the attributes cleanly; bugs should be filed to fix the APIs when these are noticed, but they do not need to be fixed for the 4.1 release.
- Modifiers
- We propose two modifiers, of which zero or more may apply to any attribute, method, or event:
- deprecated
- This modifier is advisory only; we advise you not to use this api because it is deprecated. It still works in this release, so we have backward compatability for release floor(currentversion)-1.0. The next major release will often remove this API. The presence of this modifier is a warning to stop using that API and start using a recommended API.
- class attribute | class method
- Formerly known as static, now renamed.
- Live examples
- Live examples must work inline in the reference. Clicking the edit button must bring up the editor jsp.
- In each of the reference, the developers guide, and the tutorials:
- Live examples must work inline.
- Live examples must be formatted reasonably:
- All the sample code must fit into the grey box, wrapped where necessary.
- The sample code must be character-for-character correct to the actual running code. Whitespace differences are allowed, but all punctuation including brackets, quotes, and ampersands must match the actual running code.
- There must be an edit button displayed for each live example.
- The edit button must display the edit button image.
- Clicking on the edit button must open editor.jsp in another frame with the examples code loaded into the editor.
- Other Documentation Tools issues to repair for 4.1
- Support the continuing work on the developers guide.
- Make links between developers guide and reference work correctly for all well-formed links. Links with errors in their urls in the source will be filed as bugs and dealt with by the documentation content team as time allows.
- Work items to be ignored for 4.1
- Do not make examples work in dhtml. Do not add ui for running examples in dhtml.
- Do not worry about comprehensive index at all -- ship it since it exists, but dont redesign or improve it.
- Minor cosmetic issues.
- Do not deal with contributors guide; do not build, ship, or QA it
- Do not deal with reference for charting and graphing; do not QA it, do not fix bugs in it. Turn it off from being built if that is easy.
- The kernel will not be documented.
- Tuckers proposal about efficiency optimizations with un-constrainable attributes will not be dealt with for the 4.1 release.
- Doctools Tasks for 2008 (not a complete list, not in priority order.)
- Make nav run in dhtml and swf. Provide ui for switching nav between dhtml and swf.
- Tools issues beyond reference guide
- Linking between devguide and refguide
- PDF generation
- Make doctools available to webtop
- Search
- Design search functionality
- Implement search functionality
- Make examples work in dhtml.
- Understand markup for which runtimes examples should run in. Extend if necessary.
- Make all examples work in dhtml
- Provide UI for switching examples between dhtml and flash
- Provide markup and ui for specifying examples that are expected to only work in one runtime by design (e.g., rotation examples will only work in swf, as designed)
- Determine which examples dont currently run in dhtml. Either make them run in dhtml, or mark them as by-design swf only, or annotate them as currently broken in dhtml, and file a bug.
- Indices
- Design desired indices
- Implement desired indices
- Examples
- Design directory structure for examples, such that examples can be grouped according to runtime in which they are expected to run. 
- Design & implement automated testing harness so that examples can be differentially tested accordingly.
Documentation Pudding Reviews
