Tools
Generating Reports Documents : Reference
com.jmetra.JMetraDoc [options] [aggr metrics directory] [doc output directory]
| Argument | Description | Default |
| aggr metrics directory | directory source where existing aggregated metrics files root is located. | |
| doc output directory | directory destination for generated file(s). |
| Option | Description | Default |
| -help | print all the usage arguments and options, and their descriptions. | |
| -verbose | enable verbose output. | |
| -trace | enable debug level logging. Not recommended unless user is experiencing a possible problem with jMetra and wishes to collect more details for passing to hyperCision | |
| -xaxis <scaling type> | specify the type of scaling for the X-axis for all the statistics charts. bytime scales the X-axis in terms of time, bysample scales the X-axis per sample for that particular class or package. bynormsample scales the X-axis per sample, but normalizes it so the same sampling axis is used across the entire project. | The default is bytime |
| -fromlabel <labelname> | specify the metrics to be used when calculating the change in statistics with the most recently collected metrics. The metrics are identfied by the unique label associated with it. | The metrics collected directly previous to the most recent metrics will be used. |
| -package <package list> | package list contains the list of packages to be included in the documentation generation. | All packages are included by default. |
| -incparents | this option is only relevant when the -package is used. | by default, it includes parents of specified packages. |
| -css <filename> | specify a custom css for the documentation to use. The default css should be used as a starting point. | use css contained in jmetra.jar |
| -templates <path> | specify the directory of a custom set up template files used to generate the jmetra doc. The default templates should be used as a starting point. | use templates contained in jmetra.jar |
| -logconfig <log4j config filename> | specify custom log4j configuration. Refer to the default file before customizing. | use log4j.properties contained within jmetra.jar |
Generating HTML-base Documentation
The generated output is a series of html documents representing the metrics collected over time, based in the aggr metrics directory.
The project overview page captures a bird's eye view of the project by providing the LOCC, method count, and class count for each of the project packages based on the metrics from the most recently aggregated build. Note that the metrics identified on the overview page and in the individual pages fall into two categories, Summed and Not Summed. Summed metrics include the summation of metrics for a specified package and all its subpackages. For example, LOCC represents the counted lines of code for the particular package. Summed LOCC represents the summed counted lines of code for the package and all the subpackages. For each of the statistics, a percentage shows the size of the measurement compared to the summation of that statistic for the entire project.
The project overview page also shows a measurement for the differences between the current build and the previous build (that were aggregated). For simplicity, only the differences (deltas) are shown for the summed metrics. These differences can be used to monitor project changes that are occuring over time. jMetra 1.2 only shows the differences in the metrics themselves. Future versions of jMetra will actually make difference measurements by comparing the two versions of source code - a more valid, insightful measure of the amount of change.
Usage Examples
The following are a collection of example usages to demonstrate the parameters in use. We assume all required jMetra are on the classpath.
\bin>java com.jmetra.JMetraDoc D:\proj\metrics\aggr D:\proj\doc
\bin>java com.jmetra.JMetraDoc -package com.proj D:\proj\metrics\aggr D:\proj\doc
\bin>java com.jmetra.JMetraDoc -css D:\proj\css\myjmetra.css -package com.proj D:\proj\metrics\aggr D:\proj\doc
\bin>java com.jmetra.JMetraDoc -package com.proj;com.app -incparents D:\proj\metrics\aggr D:\proj\doc
Identification of Old / Not Current Code
Classes and packages which are not currently present in the project (i.e. not present in the aggregated build with the most recent timestamp) are identified by a * (red asterisk) in package or class lists. The jMetraDoc pages for these packages or classes will also identify in red text that the package or class is not currently in the project.
Using a Custom Cascading Style Sheet (CSS)
The generated jMetraDoc will automatically generate and use a default css. The user can inspect the default css, modify it, and have jMetra use this customized css by specifying it as a command line option. (see above).
Customizing the jMetra Doc Pages (for advanced users)
Since the jMetraDoc is generated from a set of baseline templates, advanced users may modify these templates to change the layout of the generated pages. A baseline set of templates is provided with the delivered product, but customized versions may be specified on the command line. Users can integrate their metrics pages with links to over reference documentation like JavaDoc or other analysis tools. For more information go to Customizing Metrics Doc.
