SmalltalkDoc at Smalltalk Solutions

Some people might might find the title of this blog a bit strange, since there was no talk or BOF or panel about SmalltalkDoc at Smalltalk Solutions in Orlando. Only, there was someone who demoed it to a variety of people and got their opinions and ideas -- me.

SmalltalkDoc is intended to be a comprehensive documentation scheme for Smalltalk domain objects: bundles, packages, classes, namespaces, protocols, methods, variables, events, and exceptions, plus a hierarchy of overview documents -- not that there is any expectation that anyone but the most compulsive, obsessive programmers will ever actually document everything about their code. But if everything can be documented according to a consistently defined schema, then over time the Smalltalk community will figure out what should be documented and under what circumstances.

Mark Roberts originated the SmalltalkDoc project, and together we worked out its documentation schema, which takes the form of a domain model for processing and isomorphic XML tags for storage and export. I have been working on a documentation entry and editing tool, as an additional tab for the Refactoring Browser (now available in VisualWorks 7.3.1 as a preview), and Mark is working on a web application for documentation presentation.

Here are some of the comments I received:

• It was immediately obvious to Vasilli Bykov that the ability of each Smalltalk object to store its own documentation in the store was crucial to fully integrating SmalltalkDoc into the overall Smalltalk system. I showed him how my code was compensating for the fact that (in VW) only bundles, packages, namespaces and classes currently have that ability. I had been forced to nest the XML of other documents in the XML of their containing documents -- a complex process.

  There has been work on a proposal to have methods and shared variables also store their documentation. That still leaves protocols, variables and events without anywhere else to store documentation. The underlying cause of this problem is that these entities are not reified as objects. They are represented as strings or symbols handled by the compiler or by methods; sensible designs, but not very object-oriented.

  Events, however, could very well have been reified, as are Exceptions. In a later meeting, Vasilli mentioned he had discussed this with Sam Shuster (the primary VW user of events at this point) and he was willing to look into this further.

  For the rest, Vasilli liked my use of "surrogates" as intermediate objects between documents and their Smalltalk objects, even where there are no actual corresponding Smalltalk objects. He thought that perhaps it would be possible to have information about these surrogates kept in Store. Something else to think about.

• Mark and I have discussed the eventual use of WithStyle by the Documentation tool, so I demoed SmalltalkDoc for Michael Lucas-Smith. Currently, it uses the TwoFlower widget to display a document as an HTML page, but TwoFlower is a limited browser with no CSS or editing capabilities. As a result, I had to provide a separate set of windows for entering and editing document elements, some of which require the entry of XHTML tagged text. Michael claimed that WithStyle can provide all the required capabilities in a single WYSIWYG widget, though some enhancements would be necessary.
• The SmalltalkDoc domain model is currently incomplete in that it accommodates package extensions but not package overrides. Bob Westergard helped me to better understand overrides and how SmalltalkDoc should handle them, though I'm going to have to write it all out and ask him to correct me where I have it wrong.
• I wrote a comprehensive set of SUnit tests for the SmalltalkDoc domain model (some 350 test cases), but not for the rest due to time constraints. In particular, I had no real idea how to go about testing GUIs. Attending Sam Shuster's talk on "Cooking with SUnit" helped answer a lot of my questions. But Sam went further than that, he spent time with me looking at my SUnit tests and showing me Pollock examples that I could emulate. Thanks Sam.
• The perennial question of why Smalltalk isn't marketed better has been answered by Cincom. They now have Suzanne Fortmann, "marketing volcano," who gave an overview talk on Cincom's Smalltalk business. Good things are now happening. During the extensive discussions that followed her talk, Eliot Miranda remarked that the lack of adequate documentation remained a major stumbling block for Smalltalk users. He then cited the SmalltalkDoc project as a possible solution. Having this said in public is a good indication that Mark is making headway within the VW engineering group on this issue. Now all he has to do is get additional funding for the project.