ROSE  0.9.10.54
AstDiagnostics.docs
1 // Author: Dan Quinlan and Markus Schordan
2 // $Id: AstDiagnostics.docs,v 1.2 2006/04/24 00:21:31 dquinlan Exp $
3 
4 // **********************************************************************************
5 // DESCRIPTION OF AST DIAGNOSTICS
6 // **********************************************************************************
7 
8 // Removed from doxygen. Reasons: incomplete and vaporware.
9 /*
10 \defgroup astDiagnostics Description of AST Diagnostics within ROSE
11 
12  This page specifies what mechanisms we provide to test the AST.
13 More details are at \ref AstDiagnosticsClasses.
14 Analysis of the AST is separated into consistency tests, warnings
15 about questionable AST configurations, and statistical properties
16 of the AST.
17  -# Consistency tests are pass/fail and all are requred to
18  pass to verify correctness of the AST.
19  -# Warnings represent the detection of patterns of IR nodes which
20  are not presently disallowed, but which might be problematic.
21  Likely they will work for the unparser to generate code, but are
22  incorrect in ways that would lead to incorrect analysis. In general
23  the unparser will generate good code from an AST which can still
24  contain errors (e.g the unparse does not require that the symbols
25  in the symbol table be correct, but many forms of program analysis
26  might use this information).
27  -# Statistical properties of the AST report on a number of issues
28  relavant to debugging the AST (testing coverage, etc.).
29 
30 \section ASTConsistencyTests AST Consistency Tests
31 
32  Current tests are pass/fail and test the following properties:
33  -# parent pointers are verified correct
34  -# file info objects are verified to be correct, none are set to default values
35  (filename="NULL_FILE",line number =0, column number = 0) except for compiler generated
36  IR nodes.
37  -# pointers to file info objects are verified to be valid pointers
38  -# all file info objects are verified to be unique (non-shared)
39  -# the type of a SgFunctionRefExp is always a SgFunctionType.
40  -# ... \n
41 
42 \subsection FutureTests Future Consistency Tests
43 
44  There are a number of tests planned for the near future:
45  -# SgInitializedName diagnostics
46  -# correct configuration of SgExpressionRoot (SgReturnStmt)
47  -# Complete list in ROSE/proposals/TODO.txt
48 
49 \section ASTWarnings AST Warnings
50 
51  There are a number of warnings that are output if certain parterns of IR usage are
52  found:
53  -# Uniquness of file info objects in AST.
54 
55 \subsection FutureWarnings Future Warnings
56 
57  A number of warnings are planed for the near future:
58  -# correct usage of SgInitializedName
59  -# etc. (see list in TODO.txt).
60 
61 \section ASTStatisticalProperties AST Statistical Properties
62 
63  The AST has about 240 IR nodes and so this section is focuced on the
64 statistical useage of IR nodes within the AST. Current statistical
65 properties of the AST supported are:
66  -# percentage of use of each IR node in the AST.
67 
68 \subsection FutureStaticitalTests Future Statistical Properties
69  It is easy to imagin additional ASt properties to report. Future
70 work will implement a numbe of tests useful for debugging the AST:
71  -# percentage of AST that passes all tests.
72  -# percentage of AST which generates warnings.
73 
74 
75 */
76 
77 // DQ (12/1/2006): I have lifted this information of the documentation to be generated
78 // since it is always dated and does not reflect the number of people who contribute.
79 
80  \authors Schordan and Quinlan
81  \version 0.5
82  \date $Date: 2006/04/24 00:21:31 $
83  \bug No known bugs.
84  \warning Documentation is still incomplete.
85  \todo Finish documentation!
86 
103  \authors Quinlan and Schordan
104