Documentation

Author: NathanJPhillips

env-model-generator/package.json

@@ -16,6 +16,7 @@
     "build": "tsc",
     "lint": "tslint src/**/*.ts",
     "fix-lint": "tslint src/**/*.ts --fix",
+    "gen-docs": "typedoc --out doc",
     "start": "node built/env-model-generator.js ../benchmarks/GENUINE/sakai/edu-services/cm-service/cm-impl/hibernate-impl/impl/src/test/spring-test.xml --outputPath output"
   },
   "dependencies": {
@@ -32,6 +33,7 @@
     "@types/xml2js": "0.4.2",
     "tslint": "5.4.2",
     "tslint-language-service": "0.9.6",
+    "typedoc": "^0.11.1",
     "typescript": "2.4.1"
   }
 }

env-model-generator/src/parseJson.ts

@@ -10,15 +10,30 @@ interface NamedComponent {
   component: jsonConfig.Component;
 }
 
+/**
+ * [[BeanDefinitionMethod]] does not include the name of the method or the name of the class it is defined in; these are provided by the context.
+ *
+ * This class therefore combines these bits of information to act as the value to be used in a map from calculated identifiers to bean definition
+ * methods.
+ */
 interface NamedBeanDefinitionMethod {
   className: string;
   name: string;
   method: jsonConfig.BeanDefinitionMethod;
 }
 
+// A map from identifiers to components discovered in the JSON file.
 const componentsById = new Map<string, NamedComponent>();
+// A map from identifiers to bean definition methods discovered in the JSON file.
 const beansById = new Map<string, NamedBeanDefinitionMethod>();
 
+/**
+ * Collect beans from the JSON configuration file without parsing them.
+ *
+ * This allows us to set up objects that can be used to resolve circular references discovered later during parsing.
+ * @param filePath  The path to the configuration file to read the input from
+ * @returns         Paths to other config files to also include
+ */
 export async function collectBeansFromConfigFile(filePath: string): Promise<string[]> {
   let json: string;
   try {
@@ -60,7 +75,12 @@ export async function collectBeansFromConfigFile(filePath: string): Promise<stri
   return [];
 }
 
-// Check for duplicate ids from other beans
+/**
+ * Check for duplicate ids from other beans or aliases
+ * @param id                The bean identifier to check
+ * @param location          The location to include in the text of any thrown exception
+ * @throws [[ConfigParseError]] If the bean identifier has already been used
+ */
 function checkBeanId(id: string, location: string): void {
   if (componentsById.has(id))
     throw new ConfigParseError(`${location}: There is an existing component with id '${id}'`);
@@ -71,10 +91,18 @@ function checkBeanId(id: string, location: string): void {
     throw new ConfigParseError(`${location}: There is an existing alias with identifier '${aliasedBeanId}'`);
 }
 
+/**
+ * Check whether a bean identifier is already implemented by an element from the JSON configuration
+ * @param id  The bean identifier to check
+ * @returns   True if the bean identifier is already registered
+ */
 export function beanWithIdExists(id: string): boolean {
   return componentsById.has(id) || beansById.has(id);
 }
 
+/**
+ * Create the model for each bean discovered during the execution of [[collectBeansFromConfigFile]]
+ */
 export function parseAllBeans(): void {
   for (const [ beanId, component ] of componentsById) {
     if (model.Bean.tryGet(beanId) !== undefined)
@@ -90,6 +118,11 @@ export function parseAllBeans(): void {
   }
 }
 
+/**
+ * Create the model for a bean with the given identifier
+ * @param id The identifier of a bean implemented by a component or bean definition method
+ * @returns         The model for the bean
+ */
 export function parseBean(id: string): model.Bean {
   const component = componentsById.get(id);
   if (component !== undefined)
@@ -100,6 +133,12 @@ export function parseBean(id: string): model.Bean {
   throw new Error("Called parseBean on a bean that did not exist");
 }
 
+/**
+ * Create the model for a bean with the given identifier defined by a component from the JSON configuration file
+ * @param id        The identifier of a bean implemented by a component
+ * @param namedBean The component definition from the JSON configuration file
+ * @returns         The model for the bean
+ */
 function parseJsonComponent(id: string, namedBean: NamedComponent): model.Bean {
   const component = namedBean.component;
   const properties: model.BeanProperty[] = [];
@@ -115,6 +154,12 @@ function parseJsonComponent(id: string, namedBean: NamedComponent): model.Bean {
   return new model.Bean(undefined, id, namedBean.qualifiedClassName, false, [], properties);
 }
 
+/**
+ * Create the model for a bean with the given identifier defined by a component from the JSON configuration file
+ * @param id          The identifier of a bean implemented by a bean definition method
+ * @param namedMethod The bean definition method definition from the JSON configuration file
+ * @returns           The model for the bean
+ */
 function parseJsonBean(id: string, namedMethod: NamedBeanDefinitionMethod): model.Bean {
   const fieldBeanId = model.Bean.tryGetIdByClass(namedMethod.className);
   if (fieldBeanId === undefined)