org.sandev.generator
Class FuncSpecGenerator

java.lang.Object
  org.sandev.generator.GeneratorCommon
      org.sandev.generator.FuncSpecGenerator

All Implemented Interfaces:

org.sandev.sandbuild.SandGenerator

public class FuncSpecGenerator
extends GeneratorCommon
implements org.sandev.sandbuild.SandGenerator

Write out a functional specification website off the driving project docs area. This generator is run from the deployment project build (eg deploy/xyzmain) with the primary source project (eg apps/xyz) specified in the extra parameter of the sandgenerator build declaration. Output is to the docs/funcspec area of the deployment project.

Note that any supporting images or documents will have to be copied into the funcspec directory separately as part of the build script for the deployment. This generator doesn't traverse links yet.

The functional specification is built from:

• apps/xyz/docs/Objective.html
• apps/xyz/docs/UserStories.html
• apps/xyz/docs/UIReqs.html
• apps/xyz src structs and any structs they extend
• apps/xyz src nodes and all nodes in all upstream required projects
• deploy/xyz/docs/intro.html
• deploy/xyz/docs/TaskHeapData.html

Finding TaskHeapData.html off the deployment allows for flexibility when managing multiple deployments of the same app. However if no TaskHeapData.html file is found off the deployment, then we look for it off the driving application.

Field Summary

protected static int	ALLSTRUCTS
static java.lang.String	helpDeploy
static java.lang.String	helpObjective
static java.lang.String	helpTaskHeap
static java.lang.String	helpUIReqs
static java.lang.String	helpUserStories
protected static int	PERSISTSTRUCTS
protected static int	RUNTIMESTRUCTS

Fields inherited from class org.sandev.generator.GeneratorCommon

CONTEXT_CONFIGURATION, CONTEXT_CONTROL, CONTEXT_FRAMEWORK, CONTEXT_MESSAGING, CONTEXT_PERSISTENCE, CONTEXT_UI, DEFAULT_LINE_LENGTH, MESSAGE_INTERFACES

Constructor Summary

FuncSpecGenerator()

Method Summary

protected static boolean	attachToTree(org.sandev.sandbuild.SandDeclTreeWrapper root, org.sandev.sandbuild.SandDeclTreeWrapper orphan) Find the parent of the orphan and hook it up.
void	cleanup(org.sandev.sandbuild.SandDecl[] decls, java.io.File baseDir, boolean changed, java.lang.String extra) Clean up the files we wrote.
protected void	dumpGeneratedComments(java.io.PrintStream out, com.sun.javadoc.FieldDoc fd, java.lang.String indent) Dump out any additional generated comments for this field.
protected java.lang.String	filterHTMLLine(java.lang.String line) If the given line contains a node documentation link to be substituted then make that happen.
void	generate(org.sandev.sandbuild.SandDecl[] decls, java.io.File baseDir, boolean changed, java.util.Collection dirtyFiles, java.lang.String extra) Create the functional specification website files.
static org.sandev.sandbuild.SandDeclTreeWrapper	getAppStructDecls(org.sandev.sandbuild.SandDecl[] decls, java.lang.String srcPrefix) Given an array of declarations, return all the struct declarations for the app, as identified by the source prefix.
protected java.lang.String	getFieldNameText(com.sun.javadoc.FieldDoc fd) Return the display text for this field
java.lang.String	getFirstHTMLSentence(java.lang.String filespec) Return the first sentence from the body of the given HTML file.
static boolean	structsChanged(org.sandev.sandbuild.SandDeclTreeWrapper root) Return true if any of the declarations in the tree have changed, false otherwise.
protected void	verifyDeploy(java.lang.String depdocs, java.lang.String specdir, boolean changed, java.lang.String switches) Write the deployment document.
protected static boolean	verifyHierarchy(org.sandev.sandbuild.SandDeclTreeWrapper root, org.sandev.sandbuild.SandDecl[] decls) Return false, and fix the failing reference, if at any point a recursive depth first traversal of the hierarchy shows the tree is not correct.
protected void	verifyIndex(java.lang.String appdocs, java.lang.String depdocs, java.lang.String specdir, java.lang.String depname, boolean changed) Write the index file for the func specs.
protected void	writeBannerFrame(java.lang.String specdir, java.lang.String obfilename) Write out the contents of the banner frame.
protected void	writeDeclTree(java.io.PrintStream out, org.sandev.sandbuild.SandDeclTreeWrapper root, java.lang.String prefix, int includeMode) Write out the given SandDeclTreeWrapper, recursing into each child as necessary.
protected void	writeIndexFile(java.lang.String indexfilename, java.lang.String obfilename, java.lang.String genlinkfilename, java.lang.String depname) Write out the main index file frameset.
protected void	writeIndexTOC(java.io.PrintStream out, java.lang.String genlinkfilename, java.lang.String obfilename) Write the links for the func specs.
protected void	writeNavFrame(java.lang.String specdir, java.lang.String obfilename, java.lang.String genlinkfilename, java.lang.String depname) Write out the contents of the navigation frame.
protected void	writeNodeDescription(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd) Write out a description of the node declaration.
protected void	writeNodeDoc(org.sandev.sandbuild.SandDecl[] decls, java.lang.String specdir, boolean changed, java.lang.String switches) Walk through the decls, grabbing the nodes and writing out a doc describing them.
protected void	writeStructDecl(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd) Write out a description of the struct declaration.
protected void	writeStructDetails(java.io.PrintStream out, org.sandev.sandbuild.SandDeclTreeWrapper root) Write out a descriptive page for each struct declaration.
protected void	writeStructDoc(org.sandev.sandbuild.SandDecl[] decls, java.lang.String appdocs, java.lang.String specdir, boolean changed, java.lang.String switches) Walk through the decls, grabbing only those structs whose src is adjacent to the appdocs area.
protected void	writeStructFile(java.lang.String filename, org.sandev.sandbuild.SandDeclTreeWrapper root, java.lang.String switches) Write out a file with the struct declarations.

Methods inherited from class org.sandev.generator.GeneratorCommon

capitalize, copyfile, deletefile, findStructDeclByShortname, getDeclaredFields, getFields, getInheritanceHierarchy, getLastAppProject, getLastUtilDir, getLongInstanceName, getPrintStream, getSandProject, getShortInstanceName, getUtilPackage, getVisibleFields, hasSubStructs, isArray, isBasic, isLongReferenceArray, isMessageInterface, isParentAbstract, isPrimitive, isRootStruct, isVowel, log, nextToken, pluralize, rangeEscape, removePlatformDecls, trackFileDelete, trackFileWrite, uncapitalize, writeDefaultCtor, writeDescription, writeHTMLContents, writeMessageImports, writeSectionName, writeStandardCommentID, writeXHTMLFooter, writeXHTMLFooter, writeXHTMLHeader, writeXHTMLHeader

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

helpObjective

public static final java.lang.String helpObjective

See Also:

Constant Field Values

helpUserStories

public static final java.lang.String helpUserStories

See Also:

Constant Field Values

helpUIReqs

public static final java.lang.String helpUIReqs

See Also:

Constant Field Values

helpDeploy

public static final java.lang.String helpDeploy

See Also:

Constant Field Values

helpTaskHeap

public static final java.lang.String helpTaskHeap

See Also:

Constant Field Values

ALLSTRUCTS

protected static final int ALLSTRUCTS

See Also:

Constant Field Values

PERSISTSTRUCTS

protected static final int PERSISTSTRUCTS

See Also:

Constant Field Values

RUNTIMESTRUCTS

protected static final int RUNTIMESTRUCTS

See Also:

Constant Field Values

Constructor Detail

FuncSpecGenerator

public FuncSpecGenerator()

Method Detail

generate

public void generate(org.sandev.sandbuild.SandDecl[] decls,
                     java.io.File baseDir,
                     boolean changed,
                     java.util.Collection dirtyFiles,
                     java.lang.String extra)
              throws org.sandev.sandbuild.SandGeneratorException

Create the functional specification website files. Basically this creates ../docs/funcspec/index.html and copies supporting files over as needed.

Specified by:

generate in interface org.sandev.sandbuild.SandGenerator

Throws:

org.sandev.sandbuild.SandGeneratorException

cleanup

public void cleanup(org.sandev.sandbuild.SandDecl[] decls,
                    java.io.File baseDir,
                    boolean changed,
                    java.lang.String extra)
             throws org.sandev.sandbuild.SandGeneratorException

Clean up the files we wrote.

Specified by:

cleanup in interface org.sandev.sandbuild.SandGenerator

Throws:

org.sandev.sandbuild.SandGeneratorException

verifyIndex

protected void verifyIndex(java.lang.String appdocs,
                           java.lang.String depdocs,
                           java.lang.String specdir,
                           java.lang.String depname,
                           boolean changed)
                    throws org.sandev.sandbuild.SandGeneratorException

Write the index file for the func specs.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeIndexFile

protected void writeIndexFile(java.lang.String indexfilename,
                              java.lang.String obfilename,
                              java.lang.String genlinkfilename,
                              java.lang.String depname)
                       throws org.sandev.sandbuild.SandGeneratorException

Write out the main index file frameset.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeBannerFrame

protected void writeBannerFrame(java.lang.String specdir,
                                java.lang.String obfilename)
                         throws org.sandev.sandbuild.SandGeneratorException

Write out the contents of the banner frame.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeNavFrame

protected void writeNavFrame(java.lang.String specdir,
                             java.lang.String obfilename,
                             java.lang.String genlinkfilename,
                             java.lang.String depname)
                      throws org.sandev.sandbuild.SandGeneratorException

Write out the contents of the navigation frame.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeIndexTOC

protected void writeIndexTOC(java.io.PrintStream out,
                             java.lang.String genlinkfilename,
                             java.lang.String obfilename)
                      throws org.sandev.sandbuild.SandGeneratorException

Write the links for the func specs.

Throws:

org.sandev.sandbuild.SandGeneratorException

getFirstHTMLSentence

public java.lang.String getFirstHTMLSentence(java.lang.String filespec)
                                      throws org.sandev.sandbuild.SandGeneratorException

Return the first sentence from the body of the given HTML file. This reads past the body tag start, then searches forward to the next ". ", then reads backward to the first tag close and returns that as the result string.

Throws:

org.sandev.sandbuild.SandGeneratorException

getAppStructDecls

public static org.sandev.sandbuild.SandDeclTreeWrapper getAppStructDecls(org.sandev.sandbuild.SandDecl[] decls,
                                                                         java.lang.String srcPrefix)
                                                                  throws org.sandev.sandbuild.SandGeneratorException

Given an array of declarations, return all the struct declarations for the app, as identified by the source prefix.

This works by walking the declarations and rejecting any that are not structs, or whose file specification does not start with the given source prefix. After finding the app structs, this walks the inheritence tree upwards to bring in any other structs from other applications that were extended within this app.

Throws:

org.sandev.sandbuild.SandGeneratorException

verifyHierarchy

protected static boolean verifyHierarchy(org.sandev.sandbuild.SandDeclTreeWrapper root,
                                         org.sandev.sandbuild.SandDecl[] decls)
                                  throws org.sandev.sandbuild.SandGeneratorException

Return false, and fix the failing reference, if at any point a recursive depth first traversal of the hierarchy shows the tree is not correct.

Throws:

org.sandev.sandbuild.SandGeneratorException

attachToTree

protected static boolean attachToTree(org.sandev.sandbuild.SandDeclTreeWrapper root,
                                      org.sandev.sandbuild.SandDeclTreeWrapper orphan)

Find the parent of the orphan and hook it up. Return true if successful, false otherwise.

structsChanged

public static boolean structsChanged(org.sandev.sandbuild.SandDeclTreeWrapper root)

Return true if any of the declarations in the tree have changed, false otherwise.

writeStructDoc

protected void writeStructDoc(org.sandev.sandbuild.SandDecl[] decls,
                              java.lang.String appdocs,
                              java.lang.String specdir,
                              boolean changed,
                              java.lang.String switches)
                       throws org.sandev.sandbuild.SandGeneratorException

Walk through the decls, grabbing only those structs whose src is adjacent to the appdocs area. So if extra is defined as "apps/TaskHeap", then we skip any SandDecl whose sourceFile specification does not contain this substring (after adjusting for the OS platform).

Throws:

org.sandev.sandbuild.SandGeneratorException

writeStructFile

protected void writeStructFile(java.lang.String filename,
                               org.sandev.sandbuild.SandDeclTreeWrapper root,
                               java.lang.String switches)
                        throws org.sandev.sandbuild.SandGeneratorException

Write out a file with the struct declarations.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeDeclTree

protected void writeDeclTree(java.io.PrintStream out,
                             org.sandev.sandbuild.SandDeclTreeWrapper root,
                             java.lang.String prefix,
                             int includeMode)

Write out the given SandDeclTreeWrapper, recursing into each child as necessary. The top level output can be filtered to include persistent structs, non-persistent (runtime) structs, or both.

writeStructDetails

protected void writeStructDetails(java.io.PrintStream out,
                                  org.sandev.sandbuild.SandDeclTreeWrapper root)
                           throws org.sandev.sandbuild.SandGeneratorException

Write out a descriptive page for each struct declaration.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeStructDecl

protected void writeStructDecl(java.io.PrintStream out,
                               com.sun.javadoc.ClassDoc cd)
                        throws org.sandev.sandbuild.SandGeneratorException

Write out a description of the struct declaration.

Throws:

org.sandev.sandbuild.SandGeneratorException

getFieldNameText

protected java.lang.String getFieldNameText(com.sun.javadoc.FieldDoc fd)

Return the display text for this field

dumpGeneratedComments

protected void dumpGeneratedComments(java.io.PrintStream out,
                                     com.sun.javadoc.FieldDoc fd,
                                     java.lang.String indent)

Dump out any additional generated comments for this field. Things like enumeration values and so forth.

writeNodeDoc

protected void writeNodeDoc(org.sandev.sandbuild.SandDecl[] decls,
                            java.lang.String specdir,
                            boolean changed,
                            java.lang.String switches)
                     throws org.sandev.sandbuild.SandGeneratorException

Walk through the decls, grabbing the nodes and writing out a doc describing them.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeNodeDescription

protected void writeNodeDescription(java.io.PrintStream out,
                                    com.sun.javadoc.ClassDoc cd)
                             throws org.sandev.sandbuild.SandGeneratorException

Write out a description of the node declaration.

Throws:

org.sandev.sandbuild.SandGeneratorException

verifyDeploy

protected void verifyDeploy(java.lang.String depdocs,
                            java.lang.String specdir,
                            boolean changed,
                            java.lang.String switches)
                     throws org.sandev.sandbuild.SandGeneratorException

Write the deployment document. As a special case, copy over images/deploy.gif from the deployment docs if found. Different deployments may have different supporting images to copy over, but this one is always needed so it's worth automating here.

Throws:

org.sandev.sandbuild.SandGeneratorException

filterHTMLLine

protected java.lang.String filterHTMLLine(java.lang.String line)

If the given line contains a node documentation link to be substituted then make that happen. Node doc links look like $NODEDOC(TaskHeapUI).

Overrides:

filterHTMLLine in class GeneratorCommon