Removed incompatible documentation style guides m04616 (85d78aa2) · Commits · aflab / astrogeology / ISIS3

isis/src/docsys/build/TechnicalInfo.xsl

+6 −0

Original line number	Diff line number	Diff line
		@@ -204,6 +204,12 @@ Deborah Lee Soltesz
		ISIS Programmers Reference</a><br/>
		An in-depth reference guide for programmers who modify the ISIS software
		</p>
		<p>
		<a href="../documents/CodingStandards/CodingStandards.html" target="_blank">
		ISIS 3 Coding Standards and Style Guide</a><br/>
		Coding standards for ISIS 3 developers
		</p>


		<xsl:for-each select="//document[normalize-space(category/categoryItem) = 'api' and
		normalize-space(category/categoryItem) != 'hidden' and

isis/src/docsys/documents/CodingStandards/CodingStandards.xml

+130 −3

Original line number	Diff line number	Diff line
		@@ -27,6 +27,7 @@
		<li><a href="#continuingLinesOfCode">Continuing Lines of Code</a></li>
		<li><a href="#logicalOperators">Logical Operators</a></li>
		<li><a href="#pointerRefFormatting">Pointers and References</a></li>
		<li><a href="#sourceCodeDocs">Source Code Documentation</a></li>
		</ol>

		<li><a href="#namingConventions">Naming Conventions</a></li>
		@@ -458,8 +459,7 @@

		<h3> <a name="pointerRefFormatting">Pointers and References</a> </h3>
		<p>
		The asterisk for pointers (*) and the ampersand for references (&) should always be
		put on the variable name or method name when possible.
		The asterisk for pointers (*) and the ampersand for references (&) should always be put on the variable name or method name when possible.
		</p>
		<p>
		For example:
		@@ -481,6 +481,121 @@
		Return to Table of Contents
		</font></a></p>

		<h3> <a name="sourceCodeDocs">Source Code Documentation</a> </h3>
		<h4> <a name="doxygenComments"></a> Doxygen </h4>
		<p>
		Isis 3 uses the <a href="http://www.doxygen.org ">Doxygen</a> documentation
		extraction software. Doxygen has extended the tag set of the
		<a href="http://java.sun.com/j2se/javadoc">javadoc documentation style</a>,
		a systematic in-code documentation style that allows pertinent documentation to
		be extracted easily. Doxygen is just one of many software packages that are
		able to extract and use javadoc documentation for a variety of purposes,
		allowing us to take advantage of a wealth of documentation extractors, IDEs,
		and other tools on the market that make our lives simpler and more productive.
		</p>
		<ul>
		<li>
		Documentation should be provided for each entity (class, method, struct,
		variable, etc.) in the source code <em>where the primary or most commonly
		used definition of that entity resides</em>. Generally, this means the
		following files contain documentation for the listed entities:
		<ul>
		<li>
		<b>Header (.h)</b>: classes, inline functions, enums, typedefs, unions,
		structs, and variables declared in the header file
		</li>
		<li>
		<b>Implementation (.cpp)</b>: member function implementations and any
		entities declared or defined in the implementation file
		</li>
		</ul>
		</li>

		<li>
		To allow Doxygen to generate external documentation specialized commenting styles
		must be used. The comments are typically before each entity but single line
		comments on the same line can be added after the entity. For example:
		<ul>
		<li>
		<b>Single line of documentation (<em>documentation line</em>)</b>
		<ul>
		<li>start documentation with string <b>//!</b> before or <b>//!<</b> after
		the code
		</li>
		<li>Before the entity
		<div class="code">
		//! my integer<br/>
		int myInteger ;
		</div>
		</li>

		<li>After the entity
		<div class="code">
		int myInteger ; //!< my integer<br/>
		</div>
		</li>
		</ul>
		</li>

		<li>
		<b>Multi-lined documentation (<em>documentation block</em>)</b>
		<ul>
		<li>Before the entity in JavaDoc style
		<div class="code">
		<pre>
		/**
		* Comment about setGlobalB here. Never place multi-lined comments
		* after the entitiy.
		*/
		void setGlobalB() {
		//! single line comment here
		g_b = 3; //!< or single line comment here
		}
		</pre>
		</div>
		</li>
		</ul>
		</li>
		</ul>
		</li>
		</ul>
		<p align="right"><a href="#top"><font size="1">
		Return to Table of Contents
		</font></a></p>

		<h4> <a name="usingHTML"></a> Using HTML </h4>
		<p>
		HTML can be used anywhere in your documentation.
		Keep it simple. Doxygen will "interpret" your HTML, so you may not get the
		desired effect. Best advice, avoid attempting special effects by just using
		the basic HTML formatting tags - bold, underline, pre, code, table (caption,
		tr, td, th), etc. and only when really necessary. Better yet, consider using
		the formatting tags in the Other Useful Tags section instead of HTML. Your
		plain old text will be pretty nicely rendered into paragraphs with automatically
		linked items and other bells and whistles. Keep your source readable: minimize
		formatting.
		</p>
		<p align="right"><a href="#top"><font size="1">
		Return to Table of Contents
		</font></a></p>

		<h4> <a name="autolinking"></a> Autolinking </h4>
		<p>
		Class, method, variable, and other entity names will be automatically linked
		in the documentation. To prevent this for a specific occurence of a name,
		use a percent sign (%) in front of the name. For example, if you have a
		class name "Histogram" and you want to prevent the linking of the word
		"Histogram" in your description because it is not referring to the class but
		to an actual histogram, use "%Histogram" to prevent the word from being linked.
		</p>
		<p>
		E-mail addresses and web addresses are also automatically linked. If a web
		address is particularly long, put it on its own line.
		</p>
		<p align="right"><a href="#top"><font size="1">
		Return to Table of Contents
		</font></a></p>

		<h2> <a name="namingConventions">Naming Conventions</a> </h2>
		<p>
		This section will cover the proper way to name applications, classes,
		@@ -1245,7 +1360,10 @@

		<h2><a name="todo">TO DO</a></h2>
		<ul>
		<li> Improve examples </li>
		<li>
		Improve examples - possibly a reference to a single canonical file in
		the source tree
		</li>
		<li> Binary Operators - Determine padding. </li>
		<li> Complete History and Documentation section
		<ol>
		@@ -1282,6 +1400,12 @@
		<li>
		Should the Disclaimer be required for all ISIS files?
		</li>
		<li>
		Should prohibition against SVN keywords be added?
		</li>
		<li>
		Mention of @file and (new?) copyright header?
		</li>
		</ul>
		</body>

		@@ -1336,6 +1460,9 @@
		<change name="Steven Lambright" date="2012-10-10">
		Added Strings section
		</change>
		<change name="JP Bonn" date="2017-02-21">
		Incorporated sections of former Style Guide
		</change>
		</history>

		</documentation>

isis/src/docsys/documents/DocStyle/DocStyle.xml

deleted100644 → 0

+0 −2838

File deleted.

Preview size limit exceeded, changes collapsed.

isis/src/docsys/documents/DocStyle/assets/Statistics.cpp

deleted100644 → 0

+0 −380

Original line number	Diff line number	Diff line
		/**
		* @file
		* $Date: 2006/10/31 23:18:12 $
		* $Revision: 1.1.1.1 $
		*
		* Unless noted otherwise, the portions of Isis written by the USGS are public domain. See
		* individual third-party library and package descriptions for intellectual property information,
		* user agreements, and related information.
		*
		* Although Isis has been used by the USGS, no warranty, expressed or implied, is made by the
		* USGS as to the accuracy and functioning of such software and related material nor shall the
		* fact of distribution constitute any such warranty, and no responsibility is assumed by the
		* USGS in connection therewith.
		*
		* For additional information, launch $ISISROOT/doc//documents/Disclaimers/Disclaimers.html
		* in a browser or see the Privacy & Disclaimers page on the Isis website,
		* http://isis.astrogeology.usgs.gov, and the USGS privacy and disclaimers on
		* http://www.usgs.gov/privacy.html.
		*/

		#include <float.h>
		#include <string>
		#include "Statistics.h"
		#include "IException.h"

		using namespace std;
		namespace Isis {
		//! Constructs an IsisStats object with accumulators and counters set to zero.
		Statistics::Statistics() {
		Reset();
		}

		//! Reset all accumulators and counters to zero.
		void Statistics::Reset() {
		p_sum = 0.0;
		p_sumsum = 0.0;
		p_minimum = DBL_MAX;
		p_maximum = -DBL_MAX;
		p_totalPixels = 0.0;
		p_validPixels = 0.0;
		p_nullPixels = 0.0;
		p_lisPixels = 0.0;
		p_lrsPixels = 0.0;
		p_hrsPixels = 0.0;
		p_hisPixels = 0.0;
		p_removedData = false;
		}

		//! Destroys the IsisStats object.
		Statistics::~Statistics() {};

		/**
		* Add an array of doubles to the accumulators and counters.
		* This method can be invoked multiple times (for example: once
		* for each line in a cube) before obtaining statistics.
		*
		* @param[in] data (const double*) data to be added to the data
		* set used for statistical calculations
		*
		* @param[in] count (const unsigned int) number of elements in the incoming
		* data to be added
		*/
		void Statistics::AddData(const double *data, const unsigned int count) {
		for(unsigned int i = 0; i < count; i++) {
		p_totalPixels++;

		if(Isis::IsValidPixel(data[i])) {
		p_sum += data[i];
		p_sumsum += data[i] * data[i];
		if(data[i] < p_minimum) p_minimum = data[i];
		if(data[i] > p_maximum) p_maximum = data[i];
		p_validPixels++;
		}
		else if(Isis::IsNullPixel(data[i])) {
		p_nullPixels++;
		}
		else if(Isis::IsHisPixel(data[i])) {
		p_hisPixels++;
		}
		else if(Isis::IsHrsPixel(data[i])) {
		p_hrsPixels++;
		}
		else if(Isis::IsLisPixel(data[i])) {
		p_lisPixels++;
		}
		else {
		p_lrsPixels++;
		}
		}
		}

		/**
		* Remove an array of doubles from the accumulators and counters.
		* Note that is invalidates the absolute minimum and maximum. They
		* will no longer be usable.
		*
		* @param[in] data (const double*) data to be removed from data
		* set used for statistical calculations
		*
		* @param[in] count (const unsigned int) number of elements in the data to be removed
		*
		* @throws Isis::iException::Message
		*/
		void Statistics::RemoveData(const double *data, const unsigned int count) {
		p_removedData = true;

		for(unsigned int i = 0; i < count; i++) {
		p_totalPixels--;

		if(Isis::IsValidPixel(data[i])) {
		p_sum -= data[i];
		p_sumsum -= data[i] * data[i];
		p_validPixels--;
		}
		else if(Isis::IsNullPixel(data[i])) {
		p_nullPixels--;
		}
		else if(Isis::IsHisPixel(data[i])) {
		p_hisPixels--;
		}
		else if(Isis::IsHrsPixel(data[i])) {
		p_hrsPixels--;
		}
		else if(Isis::IsLisPixel(data[i])) {
		p_lisPixels--;
		}
		else {
		p_lrsPixels--;
		}
		}

		if(p_totalPixels < 0) {
		string m = "You are removing non-existant data in [Statistics::RemoveData]";
		throw Isis::iException::Message(Isis::iException::Programmer, m, _FILEINFO_);
		}
		}

		/**
		* Computes and returns the average.
		* If there are no valid pixels, then NULL8 is returned.
		*
		* @return (double) average
		*/
		double Statistics::Average() const {
		if(p_validPixels < 1.0) return Isis::NULL8;
		return p_sum / p_validPixels;
		}

		/**
		* Computes and returns the standard deviation.
		* If there are no valid pixels, then NULL8 is returned.
		*
		* @return (double) standard deviation
		*/
		double Statistics::StandardDeviation() const {
		if(p_validPixels <= 1.0) return Isis::NULL8;
		return sqrt(Variance());
		}

		/**
		* Computes and returns the variance.
		* If there are no valid pixels, then NULL8 is returned.
		*
		* @return (double) variance
		*
		* @internal
		* @history 2003-08-27 Jeff Anderson - Modified Variance method to compute
		* using n(n-1) instead of nn.
		*/
		double Statistics::Variance() const {
		if(p_validPixels <= 1.0) return Isis::NULL8;
		double temp = p_validPixels * p_sumsum - p_sum * p_sum;
		if(temp < 0.0) temp = 0.0; // This should happen unless roundoff occurs
		return temp / ((p_validPixels - 1.0) * p_validPixels);
		}

		/**
		* Returns the absolute minimum double found in all data passed through the
		* AddData method. If there are no valid pixels, then NULL8 is returned.
		*
		* @return (double) current minimum value in data set
		*
		* @throws Isis::iException::Message
		*/
		double Statistics::Minimum() const {
		if(p_removedData) {
		string m = "Minimum is invalid since you removed data";
		throw Isis::iException::Message(Isis::iException::Programmer, m, _FILEINFO_);
		}

		if(p_validPixels < 1.0) return Isis::NULL8;
		return p_minimum;
		}

		/**
		* Returns the absolute maximum double found in all
		* data passed through the AddData method. If there
		* are no valid pixels, then NULL8 is returned.
		*
		* @return (double) current maximum value in data set
		*
		* @throws Isis::iException::Message
		*/
		double Statistics::Maximum() const {
		if(p_removedData) {
		string m = "Maximum is invalid since you removed data";
		throw Isis::iException::Message(Isis::iException::Programmer, m, _FILEINFO_);
		}

		if(p_validPixels < 1.0) return Isis::NULL8;
		return p_maximum;
		}

		/**
		* Returns the total number of pixels processed
		* (valid and invalid).
		*
		* @return (double) number of pixels (data) processed
		*/
		double Statistics::TotalPixels() const {
		return p_totalPixels;
		}

		/**
		* Returns the total number of valid pixels processed.
		* Only valid pixels are utilized when computing the
		* average, standard deviation, variance, minimum and
		* maximum.
		*
		* @return (double) number of valid pixels (data) processed
		*/
		double Statistics::ValidPixels() const {
		return p_validPixels;
		}

		/**
		* Returns the total number of NULL pixels encountered.
		*
		* @return (double) number of NULL pixels (data) processed
		*/
		double Statistics::NullPixels() const {
		return p_nullPixels;
		}

		/**
		* Returns the total number of low instrument
		* saturation (LIS) pixels encountered.
		*
		* @return (double) number of LIS pixels (data) processed
		*/
		double Statistics::LisPixels() const {
		return p_lisPixels;
		}

		/**
		* Returns the total number of low representation
		* saturation (LRS) pixels encountered.
		*
		* @return (double) number of LRS pixels (data) processed
		*/
		double Statistics::LrsPixels() const {
		return p_lrsPixels;
		}

		/**
		* Returns the total number of high instrument
		* saturation (HIS) pixels encountered.
		*
		* @return (double) number of HIS pixels (data) processed
		*/
		double Statistics::HisPixels() const {
		return p_hisPixels;
		}

		/**
		* Returns the total number of high representation
		* saturation (HRS) pixels encountered.
		*
		* @return (double) number of HRS pixels (data) processed
		*/
		double Statistics::HrsPixels() const {
		return p_hrsPixels;
		}

		/**
		* This method returns a minimum such that X percent
		* of the data will fall with K standard deviations
		* of the average (Chebyshev's Theorem). It can be
		* used to obtain a minimum that does not include
		* statistical outliers.
		*
		* @param[in] percent (double) The probability that the minimum
		* is within K standard deviations of the mean.
		* Default value = 99.5.
		*
		* @return minimum value excluding statistical outliers
		*
		* @throws Isis::iException::Message
		*/
		double Statistics::ChebyshevMinimum(const double percent) const {
		if((percent <= 0.0) \|\| (percent >= 100.0)) {
		string m = "Invalid value for percent";
		throw Isis::iException::Message(Isis::iException::Programmer, m, _FILEINFO_);
		}

		if(p_validPixels < 1.0) return Isis::NULL8;
		double k = sqrt(1.0 / (1.0 - percent / 100.0));
		return Average() - k * StandardDeviation();
		}

		/**
		* This method returns a maximum such that
		* X percent of the data will fall with K
		* standard deviations of the average (Chebyshev's
		* Theorem). It can be used to obtain a minimum that
		* does not include statistical outliers.
		*
		* @param[in] percent (double) The probability that the maximum
		* is within K standard deviations of the mean.
		* Default value = 99.5.
		*
		* @return maximum value excluding statistical outliers
		*
		* @throws Isis::iException::Message
		*/
		double Statistics::ChebyshevMaximum(const double percent) const {
		if((percent <= 0.0) \|\| (percent >= 100.0)) {
		string m = "Invalid value for percent";
		throw Isis::iException::Message(Isis::iException::Programmer, m, _FILEINFO_);
		}

		if(p_validPixels < 1.0) return Isis::NULL8;
		double k = sqrt(1.0 / (1.0 - percent / 100.0));
		return Average() + k * StandardDeviation();
		}

		/**
		* This method returns the better of the absolute
		* minimum or the Chebyshev minimum. The better
		* value is considered the value closest to the mean.
		*
		* @param[in] percent (double) The probability that the minimum is within K
		* standard deviations of the mean (Used to compute
		* the Chebyshev minimum). Default value = 99.5.
		*
		* @return (double) Best of absolute and Chebyshev minimums
		*
		* @see Statistics::Minimum
		* Statistics::ChebyshevMinimum
		*/
		double Statistics::BestMinimum(const double percent) const {
		if(p_validPixels < 1.0) return Isis::NULL8;
		double min = ChebyshevMinimum(percent);
		if(Minimum() > min) min = Minimum();
		return min;
		}

		/**
		*
		* This method returns the better of the absolute
		* maximum or the Chebyshev maximum. The better value
		* is considered the value closest to the mean.
		*
		* @param[in] percent (double) The probability that the maximum is within K
		* standard deviations of the mean (Used to compute
		* the Chebyshev maximum). Default value = 99.5.
		*
		* @return (double) Best of absolute and Chebyshev maximums
		*
		* @see Statistics::Maximum
		* Statistics::ChebyshevMaximum
		*/
		double Statistics::BestMaximum(const double percent) const {
		if(p_validPixels < 1.0) return Isis::NULL8;
		double max = ChebyshevMaximum(percent);
		if(Maximum() < max) max = Maximum();
		return max;
		}

		} // end namespace isis

isis/src/docsys/documents/DocStyle/assets/Statistics.h

deleted100644 → 0

+0 −132

Original line number	Diff line number	Diff line
		#ifndef Statistics_h
		#define Statistics_h
		/**
		* @file
		* $Date: 2006/10/31 23:18:12 $
		* $Revision: 1.1.1.1 $
		*
		* Unless noted otherwise, the portions of Isis written by the USGS are public domain. See
		* individual third-party library and package descriptions for intellectual property information,
		* user agreements, and related information.
		*
		* Although Isis has been used by the USGS, no warranty, expressed or implied, is made by the
		* USGS as to the accuracy and functioning of such software and related material nor shall the
		* fact of distribution constitute any such warranty, and no responsibility is assumed by the
		* USGS in connection therewith.
		*
		* For additional information, launch $ISISROOT/doc//documents/Disclaimers/Disclaimers.html
		* in a browser or see the Privacy & Disclaimers page on the Isis website,
		* http://isis.astrogeology.usgs.gov, and the USGS privacy and disclaimers on
		* http://www.usgs.gov/privacy.html.
		*/


		#include "SpecialPixel.h"

		namespace Isis {
		/**
		* @brief This class is used to accumulate statistics on double arrays.
		*
		* This class is used to accumulate statistics on double arrays. In
		* particular, it is highly useful for obtaining statistics on cube data.
		* Parameters which can be computed are 1) @b average, 2) @b standard
		* @b deviation, 3) @b variance, 4) @b minimum, 5) @b maximum and 6)
		* @b various @b counts of valid and/or special pixels.
		*
		* The following example shows a simple set up and usage of the Statistics
		* class to calculate the average of a set of values:
		*
		* @code
		* Statistics myStats ;
		* double myData [] = { 1.0, 3.0, 2.4, 7.5 } ;
		*
		* myStats.AddData (myData, 4) ;
		* double myAverage = myStats.Average () ;
		* cout << "The average of the data is " << myAverage << endl ;
		* @endcode
		*
		* For an example of how the Statistics object is used in %Isis, see the
		* Histogram object (inherits from Statistics) and the stats application,
		* stats.cpp (uses the Statistics child class Histogram).
		*
		* @ingroup Statistics
		*
		* @author Jeff Anderson - 2002-05-06
		*
		* @whatsnew 2002-05-06 The current sum and squared sum of the data can be retrieved
		* with the Sum and SumSquare methods.
		*
		* @internal
		* @history 2002-05-08 Jeff Anderson - Added Chebyshev and Best minimum/maximum methods.
		* @history 2004-05-11 Jeff Anderson - Moved Reset, AddData and RemoveData methods into public space.
		* @history 2004-06-28 Jeff Anderson - Added Sum and SumSquare methods.
		*
		* @todo 2005-02-07 Deborah Lee Soltesz - add example using cube data to the class documentation
		*
		*/
		class Statistics {
		private:
		double p_sum; //!< Sum accumulator.
		double p_sumsum; //!< Sum-squared accumulator.
		double p_minimum; //!< Minimum double value encountered.
		double p_maximum; //!< Maximum double value encountered.
		double p_totalPixels; //!< Count of total pixels processed.
		double p_validPixels; //!< Count of valid pixels (non-special) processed.
		double p_nullPixels; //!< Count of null pixels processed.
		double p_lrsPixels; //!< Count of low instrument saturation pixels processed.
		double p_lisPixels; //!< Count of low representation saturation pixels processed.
		double p_hrsPixels; //!< Count of high instrument saturation pixels processed.
		double p_hisPixels; //!< Count of high instrument representation pixels processed.
		bool p_removedData; /**< Indicates the RemoveData method was called which implies
		p_minimum and p_maximum are invalid. */

		public:
		Statistics();
		~Statistics();

		void Reset();
		void AddData(const double *data, const unsigned int count);
		void RemoveData(const double *data, const unsigned int count);

		double Average() const;
		double StandardDeviation() const;
		double Variance() const;

		double Minimum() const;
		double Maximum() const;
		double ChebyshevMinimum(const double percent = 99.5) const;
		double ChebyshevMaximum(const double percent = 99.5) const;
		double BestMinimum(const double percent = 99.5) const;
		double BestMaximum(const double percent = 99.5) const;

		double TotalPixels() const;
		double ValidPixels() const;
		double NullPixels() const;
		double LisPixels() const;
		double LrsPixels() const;
		double HisPixels() const;
		double HrsPixels() const;


		/**
		* Returns the sum of all the data
		*
		* @return (double) Sum of the data
		*/
		double Sum() const {
		return p_sum;
		};

		/**
		* Returns the sum of all the squared data
		*
		* @return (double) Sum of the squared data
		*/
		double SumSquare() const {
		return p_sumsum;
		};
		};
		} // end namespace isis