New eDocs Makes Documenting Fun!

Documentation.  This single word tends to sends shivers up the spine of many an engineer.  People like to code.  It's fun.  It's exciting.  You can simulate your code, view waveforms, debug it, collect coverage on it and play with it.  Let's face it, a Word document simply pales in comparison. 

Now, I am not saying that anyone should start coding up your verification environment without an up front plan in place, but wouldn't it be great if you could automatically document your e environment based on its implementation?  What if you could customize this documentation to show different parties as much or as little information as needed?  Well, I am here to tell all that you can! 

Automatically documenting your environment has a number of benefits and can be quite challenging to do on your own.  A long time ago on one of my earlier projects, our verification team (led by a seriously script savy manager) instrumented our e code with text tags to identify fields, methods, events, comments, structs and units of interest.  We had a nifty script that would suck in our files, parse the code and crank out HTML based documentation that contained info on structs/units/methods/fields based on the comments within the code.  Our thinking was that we would pass these docs on to testwriters so that they could quickly find the fields that they needed to constrain in testcases and better understand the environment.  While this was very useful it, of course, led to maintenance issues, extra coding, missed contents and issues with providing users the right amount of detail. 

Shortly after we created our documentation generator, eDocs was release with Specman Elite which made all of our previous efforts obsolete!  We were both loving Verisity for rolling this functionality into Specman and secretly cursing them for not telling us this was coming!  As eDocs made use of the reflection facility (See Matan's blog post for more info on the power of reflection) in e, nothing could be missed in eDocs.  As the comments for each of the fields/structs/units were automatically extracted from the code to provide descriptions, it served as the "Comment Police" and encouraged us to comment our code better so that others could more easily ramp up on our environment.  We made extensive use of eDocs in all future projects.   

The previous version of eDocs has always been very useful in that it:

• Extracts all structs/units/fields/methods/events from your environment and organizes them into a single HTML file, in tabular format
• Automatically extracts comments from your code and adds them as descriptions
• Provides hyperlinks for structs/units to allow you to dive into the objects to examine their contents

Since the 8.1 release of Specman Elite, a new eDocs replaces the previous version. The new version has been further improved to:

• Display top level package information
• Display inheritance information (OOP and AOP)
• Display hyperlinks to object declarations, as well as extensions
• Display package hierarchy
• Store all HTML files in a directory of your choice
• Provide links to e source code files for field definitions
• Contain a clickable alphabetized index of all environment contents
• Contain multiple frames
  • Structs/Package info
  • All Struct pane
  • Multi-use central frame

There are more features to discover by reading the Specman Elite documentation.  To give you a quick idea of what the new format looks like, check out the screen shot below:

Once you have generated documentation using eDocs, your documentation can be passed on to testwriters (showing only the publicly accessable fields, of course), other environment developers to assist them with integration/ramp up, bundled with your code and shipped to other teams for re-use.  eDocs can also be useful as a debugging aid as users can quickly explore environment contents to bettter understand the implemented code. Alternatively you can simply admire your new documentation and/or show it off to your management ... just because it's really cool. 

The command for launching the new eDocs is:

• write doc [options] erm_package_name|@modules

The old eDocs can still be launched via the command

• show doc [options] erm_package_name|@modules 

While most of you have probably already used the previous version of eDocs, I would urge you to give the new version a spin and let us know what you think. 

May documentation be fun for you from this moment on!

Corey Goss

Senior Technical Leader

Solution Deployment

Cadence Design Systems, Inc.