1. Thinking inside the box 26 June 2003 Soar Workshop - Slide 1 © 2003 Soar Technology, Inc. Thinking… …inside the box SoarDoc Presented on Thursday, 26 June 2003 By: David Ray ray@soartech.com

2. Thinking inside the box 26 June 2003 Soar Workshop - Slide 2 © 2003 Soar Technology, Inc. Overview Generate API and behavior-level documentation for a Soar system Documentation in-line with source code Documentation audiences –Current developer –Future maintainers –Testers Behavior Validation & Verification Subject Matter Experts

3. Thinking inside the box 26 June 2003 Soar Workshop - Slide 3 © 2003 Soar Technology, Inc. Development Philosophy Heavily influenced by Doxygen and Javadoc tools Extensive configuration options Applicable to existing systems –Produce simple documentation for uncommented code –Extract existing comments Developers can use the features they like, ignore/disable the ones they don’t

4. Thinking inside the box 26 June 2003 Soar Workshop - Slide 4 © 2003 Soar Technology, Inc. Comment Block Syntax SoarDoc requires blocks of specially formatted comments in source Start with ##! line End with first non-comment line ##! # @file filename.soar # # Detailed description of file #... #...

5. Thinking inside the box 26 June 2003 Soar Workshop - Slide 5 © 2003 Soar Technology, Inc. Command Syntax SoarDoc commands begin with @ symbol Followed by zero or more arguments Many commands allow embedded HTML markup for formatting output –Emphasis, lists, tables, hyperlinks, etc ##! # @brief A brief description # of the object with embedded # HTML markup.

6. Thinking inside the box 26 June 2003 Soar Workshop - Slide 6 © 2003 Soar Technology, Inc. Example Input ##! # @operator count-attributes # # @brief Count the atributes in the learning instance # @problem-space predict # # Instances of this operator count each feature on the # object. # # Note: You can hard-code the number of features in most # cases. This solution gives users the flexibility to # readily change the number of features. # # Soar8: A new operator is necessary because indifferent # preferences are not available in Soar8 for non-operator # WMEs. # # @ingroup soar8

7. Thinking inside the box 26 June 2003 Soar Workshop - Slide 7 © 2003 Soar Technology, Inc. Example Output

8. Thinking inside the box 26 June 2003 Soar Workshop - Slide 8 © 2003 Soar Technology, Inc. Documentable Objects Files Soar productions Soar problem-spaces Soar operators User-defined groups –Arbitrary collections of files, productions, etc. Main Page –General project information

9. Thinking inside the box 26 June 2003 Soar Workshop - Slide 9 © 2003 Soar Technology, Inc. Common SoarDoc Commands @brief – Brief description @desc – Detailed description @created – Author and creation date @modified – Modification history @devnote – Programmer notes @todo – “To do” list item

10. Thinking inside the box 26 June 2003 Soar Workshop - Slide 10 © 2003 Soar Technology, Inc. SoarDoc Output Generates set of HTML documentation Most objects get their own page –Productions are included in their file’s page Alphabetical indices of objects Hyperlinks between related objects Alternatively XML output is available –Integrate SoarDoc data into other applications

11. Thinking inside the box 26 June 2003 Soar Workshop - Slide 11 © 2003 Soar Technology, Inc. Datamap Generation dmgen –Separate tool –Build datamap by static code analysis –Generates XML representation of datamap from source productions SoarDoc generates datamap graphs from dmgen output using AT&T DOT tool Graphs included in problem-space and operator documentation

12. Thinking inside the box 26 June 2003 Soar Workshop - Slide 12 © 2003 Soar Technology, Inc. Datamap Generation Soar source productions XML Datamap dmgen SoarDoc

13. Thinking inside the box 26 June 2003 Soar Workshop - Slide 13 © 2003 Soar Technology, Inc. Auto-Generation of Comments Autodoc mode Run SoarDoc on existing code Generates comment blocks for all objects without SoarDoc-style comments Will use existing non-SoarDoc comments if desired.

14. Thinking inside the box 26 June 2003 Soar Workshop - Slide 14 © 2003 Soar Technology, Inc. Nuggets A flexible tool Useful even for existing systems Simplifies maintenance of API and behavior-level documentation Available for Linux and Windows

15. Thinking inside the box 26 June 2003 Soar Workshop - Slide 15 © 2003 Soar Technology, Inc. Coal Initial setup can be tedious –Configuring paths –Configuring dmgen requires Tcl + Soar –Installing DOT tool

16. Thinking inside the box 26 June 2003 Soar Workshop - Slide 16 © 2003 Soar Technology, Inc. Future Directions Setup wizard Cascading Style Sheet to give greater control over appearance Support for Visual Soar datamap files Output auto-generated comments as a patch file

17. Thinking inside the box 26 June 2003 Soar Workshop - Slide 17 © 2003 Soar Technology, Inc. How to get SoarDoc Available from http://www.soartech.com/downloads Follow the SoarDoc link.