Merge pull request #1109 from sleuthkit/doc_updates

JNI Doxygen updates for comm mgr

bindings/java/doxygen/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Sleuth Kit Java Bindings (JNI)"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 4.5.0 
+PROJECT_NUMBER         = 4.6.0 
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -415,7 +415,7 @@ EXTRACT_ALL            = YES
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = YES
+EXTRACT_PRIVATE        = NO
 
 # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
 # scope will be included in the documentation.
@@ -760,8 +760,9 @@ WARN_LOGFILE           =
 
 INPUT                  = main.dox \
                          query_database.dox \
-			 blackboard.dox \
+			             blackboard.dox \
                          insert_and_update_database.dox \
+                         communications.dox \
 						 ../src
 
 # This tag can be used to specify the character encoding of the source files
@@ -1046,7 +1047,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = jni-docs/4.5.0/
+HTML_OUTPUT            = jni-docs/4.6.0/
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).

bindings/java/doxygen/communications.dox

 /*! \page mod_compage Communications 
 
+
+
+NOTE: This is a work in progress
+
+
 \section jni_com_overview Overview
 
-Work in progress
+The Java code and database in Sleuth Kit contain special classes and tables to deal with communications between two parties. This page outlines what a developer should do when they are parsing communications data so that it can be properly displayed and used by other code (such as the Autopsy Communications UI). 
+
+\section jni_com_types Terminology
+
+First, lets cover the terminology that we use. 
+
+
+An <b>Account</b> is an entity with a type and an identifier that is unique to the type.  Common examples of types include:
+- Credit Card (and the unique identifier is the credit card number)
+- Email (and the unique identifier is the email address)
+- Phone (and the unique identifier is the phone number)
+- Twitter (with a unique identifier of the login)
+- ...
+
+Accounts are found in forensics when parsing structured data (such as email messages) or keyword searching.
+
+
+Two accounts have a <b>relationship</b> if they are believed to have communicated in some way.  Examples of interactions that cause a relationship are:
+- Being part of the same email message
+- Being in a call log
+- Being in an address book
+
+When there are multiple people involved with an email message, a relationship is made between each of them.  For example, if A sends a message to B and CC:s C, then there will be relationships between A <-> B, A <-> C, and B <-> C.  Relationships in The Sleuth Kit are not directional. 
+
+A <b>relationship source</b> is where we learned about the relationship.  This typically comes from Blackboard Artifacts, but may come from generic files in the future. 
+
+\section jni_com_add Adding Communication Information to Database
+
+Now lets cover what you should do when you are parsing some communications data and want to store it in the TSK database.  Let's assume we are parsing a smart phone app that has messages. 
+
+\subsection jni_com_add_acct Adding Account Instances
+
+When you encounter a message, the first thing to do is store information about the accounts.  TSK wants to know about each <i>file</i> that had a reference of the account.   You should call org.sleuthkit.datamodel.CommunicationsManager.createAccountFileInstance() for each file that you encounter a given account.   
+
+Behind the scenes, createAccountFileInstance will make an entry in the accounts table for each unique account on a given device and will make a org.sleuthkit.datamodel.BlackboardArtifact for each unique account in a given file. 
+
+If you want to create a custom account type, call org.sleuthkit.datamodel.CommunicationsManager.addAccountType(). 
+
+\subsection jni_com_add_msg Adding The Message (Source)
+
+You also need to make sure that you store the org.sleuthkit.datamodel.BlackboardArtifact that used the accounts.  You can do this before or after calling createAccountFileInstance(). The order does not matter.
+
+For a messaging app, you would make org.sleuthkit.datamodel.BlackboardArtifact objects with a type of org.sleuthkit.datamodel.BlackboardArtifact.ARTIFACT_TYPE.TSK_MESSAGE.  That artifact would store various name and value pairs using org.sleuthkit.datamodel.BlackboardAttribute.ATTRIBUTE_TYPE values. 
+
+
+\subsection jni_com_add_relationship Adding the Relationship
 
-Things to cover:
-- What to do when you encounter an Account.
--- How often should you create an 'instance'
---- Once per file so that we have traceability. 
+The final step is to create store the relationships between the accounts.  You can do this via org.sleuthkit.datamodel.CommunicationsManager.addRelationships().  This method will require you to pass in the org.sleuthkit.datamodel.AccountInstance objects that you created and the org.sleuthkit.datamodel.BlackboardArtifact that you created for the message or other source.
 
--- When do you create a relationship
---- How many are stored between who
---- What should be passed in etc.
 
-http://wiki.sleuthkit.org/index.php?title=Database_v7.2_Schema#Communications_.2F_Accounts
+\section jni_com_schema Database Schema
 
+For details of how this is stored in the database, refer to the 
+<a href="http://wiki.sleuthkit.org/index.php?title=Database_v7.2_Schema#Communications_.2F_Accounts]">wiki</a>.
 
 */

bindings/java/doxygen/footer.html

 <hr/>
-<p><i>Copyright &#169; 2011-2015 Brian Carrier.  (carrier -at- sleuthkit -dot- org)<br/> 
+<p><i>Copyright &#169; 2011-2018 Brian Carrier.  (carrier -at- sleuthkit -dot- org)<br/> 
 This work is licensed under a
 <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/us/">Creative Commons Attribution-Share Alike 3.0 United States License</a>.
 </i></p>

bindings/java/doxygen/insert_and_update_database.dox

-/*! \page insert_and_update_database_page INSERT and UPDATE
+/*! \page insert_and_update_database_page Inserting Data
 
 \section types_of_databases_available Inserting Into the Database
-This page is for people who are developing code for the Autopsy framework and need to place items into the database with SQL statements. If you are not developing Autopsy framework code (Autopsy Modules are not Autopsy framework code), you should have no need to create SQL statements to insert items into the database. If you developing an Autopsy module, please see \ref query_database_page.
+This page is for people who are developing Sleuth Kit code and need to place items into the database with SQL statements. If you are simply writing modules that read from the database (such as Autopsy ingest modules), there is nothing for you here. 
 
-Autopsy currently allows either \ref sqlite_db or \ref postgresql_db as the back-end database system for a case. Any code you write could be used with either as the backend database, at the user's discretion. Be sure to test your work with both platforms.
+The Sleuth Kit currently allows either SQLite or PostgreSQL as the back-end database system for a case. Any code you write could be used with either as the backend database, at the user's discretion. Be sure to test your work with both platforms.
 
+- For SQLite compatibility, use SQL statements supported by SQLite 3
+- For PostgreSQL compatibility, use SQL statements supported by PostgreSQL 9.4
 
-\subsection sqlite_db SQLite
-- Use SQL statements supported by SQLite 3
-- Used for Single-user cases
-- Built-in
-- No configuration required
-- Databases are stored locally
-
-\subsection postgresql_db PostgreSQL
-- Use SQL statements supported by PostgreSQL 9.4
-- Used for Multi-user cases
-- An accessible instance of PostgreSQL must be running (on a server, or locally)
-- Proper configuration to connect to this instance of PostgreSQL required
-- Databases are stored within PostgreSQL, wherever it happens to be running
-
-
-<br>
 \section insert_pitfalls_to_avoid How to Avoid Pitfalls When INSERTing into the Database
 - Do not use INSERT OR REPLACE INTO. It does not exist in PostgreSQL.
-<br>
-<br>
 - Do not use INSERT OR IGNORE INTO. It does not exist in PostgreSQL.
-<br>
-<br>
 - Do not insert [NUL characters](http://en.wikipedia.org/wiki/Null_character) into the database as UTF-8 (NUL characters are not NULL fields). Translate NUL characters to the [SUB character](http://en.wikipedia.org/wiki/Substitute_character) with the following instead:
 \code{.java}
 private String replaceNulls(String text);
 \endcode
-<br>
 
 */

bindings/java/doxygen/main.dox

@@ -6,41 +6,41 @@ These classes allow Java programs to access data extracted by The Sleuth Kit.
 
 The Sleuth Kit is primarily a C/C++ library and set of command line tools. These classes allow programs to obtain the data that TSK can produce.   The typical steps would be to use JNI to cause the TSK library to create and populate a SQLite or PostgreSQL database.  The Java classes then directly open the database and perform queries on it. 
 
-\section basics Basic
 
-NOTE: This needs to be expanded on.
+\section main_classes Types of Classes
 
-\subsection basics_add Adding Data to Case
+There are three broad types of classes in this package:
+- org.sleuthkit.datamodel.SleuthkitCase contains all of the code that deals with the backend database. 
+- org.sleuthkit.datamodel.SleuthkitJNI deals with the JNI bindings with the C/C++ code (that primarily populate the database or allow file content to be read)
+- Lots of classes that store information about specific files or volumes.  Nearly all of them implement the org.sleuthkit.datamodel.Content interface.   Files from file systems or carved files will extend org.sleuthkit.datamodel.AbstractFile. 
 
-Use SleuthkitCase.newCase() or SleuthkitCase.openCase() to return an instance of a SleuthkitCase object. To add data to the case, use SleuthkitCase.makeAdImageProcess() to get a AddImageProcess object that allows you to populate the database in the scope of a transaction and get feedback on its update process. 
 
-To add a local file (logical file) you can use methods such as SleuthkitCase.addLocalFile(). 
+\section main_workflow Basic Workflow 
 
+\subsection basics_add Adding Data to Case 
 
-\subsection basics_analyzing Analyzing Data in Case
+To get data into the database (which is needed before you get it into a Java object), you need to call some org.sleuthkit.datamodel.SleuthkitCase methods. 
 
-You can either access files directly using methods such as SleuthkitCase.findFiles() or SleuthkitCase.getAbstractFileById(). 
+To open or create a case, call org.sleuthkit.datamodel.SleuthkitCase.newCase() or org.sleuthkit.datamodel.SleuthkitCase.openCase(). 
 
-You can also access the data in its tree form by starting with SleuthkitCase.getImages() and then calling getChildren() on each of the returned objects.  See the section below on basics of the datamodel structure. 
+To add a <b>disk image</b> to the case, use org.sleuthkit.datamodel.SleuthkitCase.makeAddImageProcess() to get a org.sleuthkit.datamodel.SleuthkitJNI.CaseDbHandle.AddImageProcess object that allows you to populate the database in the scope of a transaction and get feedback on its update process. 
 
+To add a <b>local file</b> (logical file) you can use methods such as org.sleuthkit.datamodel.SleuthkitCase.addLocalFile(). 
 
-\section jni_hierarchy Class Hierarchy
 
-Flush out here on general layout. 
+\subsection basics_analyzing Analyzing Data in Case
 
-- org.sleuthkit.datamodel.Content is top-level interface and gets more specific as it goes down.
-- Types disk and file system organization concepts (org.sleuthkit.datamodel.FileSystem, org.sleuthkit.datamodel.Image, etc. )
-- org.sleuthkit.datamodel.AbstractFile is interface for various types of files with more specific classes below it ( org.sleuthkit.datamodel.DerivedFile, org.sleuthkit.datamodel.FsContent, etc.)
+You can either access files directly using methods such as org.sleuthkit.datamodel.SleuthkitCase.findFiles() or org.sleuthkit.datamodel.SleuthkitCase.getAbstractFileById(). 
 
-\section jni_blackboard The Blackboard
+You can also access the data in its tree form by starting with org.sleuthkit.datamodel.SleuthkitCase.getImages() and then calling getChildren() on each of the returned objects.  See the section below on basics of the datamodel structure. 
 
-\subpage mod_bbpage
 
+\section main_other Other Topics
 
-\section the_database The Database
-How to \subpage query_database_page
-<br>
-How to \subpage insert_and_update_database_page into the Database
+- \subpage mod_bbpage is where analysis modules (such as those in Autopsy) can post and save their results. 
+- \subpage mod_compage is where analysis modules can store and retrieve communications-related data. 
+- Refer to \subpage query_database_page if you are going to use one of the SleuthkitCase methods that requires you to specify a query. 
+- Refer to \subpage insert_and_update_database_page if you are a Sleuth Kit developer and want to avoid database issues.
 
 
 */

bindings/java/src/org/sleuthkit/datamodel/AccountDeviceInstance.java

@@ -19,7 +19,7 @@
 package org.sleuthkit.datamodel;
 
 /**
- * Encapsulates an Account existing on a given device. 
+ * Encapsulates an Account existing on a specific device.
  * 
  * There is a 1:M:N relationship between 
  * Account, AccountDeviceInstance &  AccountFileInstance
@@ -34,7 +34,7 @@ public class AccountDeviceInstance {
 	}
 
 	/**
-	 *  Returns the underlying account
+	 *  Returns the underlying Account
 	 * 
 	 * @return account
 	 */
@@ -43,7 +43,7 @@ public Account getAccount(){
 	}
 	
 	/**
-	 *  Returns the device Id
+	 *  Returns the device Id the Account existed on
 	 * 
 	 * @return device id
 	 */

bindings/java/src/org/sleuthkit/datamodel/AccountFileInstance.java

@@ -22,11 +22,12 @@
 
 /**
  * An instance of an Account in a specific file. 
- * An account may be found in multiple content
- * objects, so there can be up to one account instance per content object, 
- * and there is a 1:N relationship between Account objects and AccountFileInstance
- * objects. Currently, there is an underlying TSK_ACCOUNT artifact for every 
- * account instance. This may change in the future.
+ * An Account may be found in multiple Content
+ * objects (such as different databases) on a single device.
+ * There is a 1:N relationship between Account objects and AccountFileInstance
+ * objects. A TSK_ACCOUNT artifact is created for every account file instance.
+ *
+ * AccountFileInstances can optionally have BlackboardAttributes to store more details.
  */
 public class AccountFileInstance {
 	private final BlackboardArtifact artifact; 
@@ -38,8 +39,7 @@ public class AccountFileInstance {
 	}
 
 	/**
-	 * Gets the first occurrence of an attribute of the account instance
-	 * of a given type. 
+	 * Gets the first occurrence of an attribute by type.
 	 *
 	 * @param attrType The attribute type. 
 	 * 
@@ -52,8 +52,7 @@ public BlackboardAttribute getAttribute(BlackboardAttribute.ATTRIBUTE_TYPE attrT
 	}
 
 	/**
-	 * Adds an attribute to the account instance.  It is faster to 
-	 * add them as part of a list.
+	 * Adds an attribute.  It is faster to add them as part of a list.
 	 *
 	 * @param bbatr The attribute to add.
 	 * 
@@ -64,7 +63,7 @@ public void addAttribute(BlackboardAttribute bbatr) throws TskCoreException {
 	}
 
 	/**
-	 * Adds a collection of attributes to the account instance
+	 * Adds a collection of attributes
 	 *
 	 * @param bbatrs The collection of attributes to add.
 	 * 
@@ -75,7 +74,7 @@ public void addAttributes(Collection<BlackboardAttribute> bbatrs) throws TskCore
 	}
 	
 	/**
-	 * Gets the account of which this object is an instance.
+	 * Gets the underlying Account for this instance.
 	 *
 	 * @return The account.
 	 * 

bindings/java/src/org/sleuthkit/datamodel/CommunicationsManager.java

@@ -177,9 +177,11 @@ SleuthkitCase getSleuthkitCase() {
 	}
 
 	/**
-	 * Add an account type. Returns the type if it is already defined.
+	 * Add a custom account type that is not already defined in Account.Type.
+     * Will not allow duplicates and will return existing type if the name is
+     * already defined.
 	 *
-	 * @param accountTypeName account type name
+	 * @param accountTypeName account type that must be unique
 	 * @param displayName     account type display name
 	 *
 	 * @return Account.Type
@@ -187,7 +189,8 @@ SleuthkitCase getSleuthkitCase() {
 	 * @throws TskCoreException exception thrown if a critical error occurs
 	 *                          within TSK core
 	 */
-	public Account.Type addAccountType(String accountTypeName, String displayName) throws TskCoreException {
+    // NOTE: Full name given for Type for doxygen linking
+	public org.sleuthkit.datamodel.Account.Type addAccountType(String accountTypeName, String displayName) throws TskCoreException {
 		Account.Type accountType = new Account.Type(accountTypeName, displayName);
 
 		// check if already in map
@@ -257,7 +260,8 @@ public Account.Type addAccountType(String accountTypeName, String displayName) t
 	 * @throws TskCoreException exception thrown if a critical error occurs
 	 *                          within TSK core
 	 */
-	public AccountFileInstance createAccountFileInstance(Account.Type accountType, String accountUniqueID, String moduleName, Content sourceFile) throws TskCoreException {
+    // NOTE: Full name given for Type for doxygen linking
+	public AccountFileInstance createAccountFileInstance(org.sleuthkit.datamodel.Account.Type accountType, String accountUniqueID, String moduleName, Content sourceFile) throws TskCoreException {
 
 		// make or get the Account (unique at the case-level)
 		Account account = getOrCreateAccount(accountType, normalizeAccountID(accountType, accountUniqueID));
@@ -291,7 +295,8 @@ public AccountFileInstance createAccountFileInstance(Account.Type accountType, S
 	 * @throws TskCoreException exception thrown if a critical error occurs
 	 *                          within TSK core
 	 */
-	public Account getAccount(Account.Type accountType, String accountUniqueID) throws TskCoreException {
+    // NOTE: Full name given for Type for doxygen linking
+	public Account getAccount(org.sleuthkit.datamodel.Account.Type accountType, String accountUniqueID) throws TskCoreException {
 		Account account = null;
 		CaseDbConnection connection = db.getConnection();
 		db.acquireSingleUserCaseReadLock();
@@ -344,13 +349,13 @@ public Account getAccount(Account.Type accountType, String accountUniqueID) thro
 //		return accountInstance;
 //	}
 	/**
-	 * Add relationships between the sender and recipient account instances. All
-	 * accounts the relationship must be from the same data source.
+	 * Add one or more relationships between the sender and recipient account instances. All
+	 * account instances must be from the same data source.
 	 *
 	 * @param sender               sender account
 	 * @param recipients           list of recipients
-	 * @param relationshipArtifact relationship artifact
-	 * @param relationshipType     The type of relationship to be created
+	 * @param sourceArtifact       Artifact that relationships were derived from
+	 * @param relationshipType     The type of relationships to be created
 	 * @param dateTime             Date of communications/relationship, as epoch
 	 *                             seconds
 	 *
@@ -360,20 +365,21 @@ public Account getAccount(Account.Type accountType, String accountUniqueID) thro
 	 *                                                  and the relationship are
 	 *                                                  not from the same data
 	 *                                                  source, or if the
-	 *                                                  relationshipArtifact and
+	 *                                                  sourceArtifact and
 	 *                                                  relationshipType are not
 	 *                                                  compatible.
 	 */
+    // NOTE: Full name given for Type for doxygen linking
 	public void addRelationships(AccountFileInstance sender, List<AccountFileInstance> recipients,
-			BlackboardArtifact relationshipArtifact, Relationship.Type relationshipType, long dateTime) throws TskCoreException, TskDataException {
+			BlackboardArtifact sourceArtifact, org.sleuthkit.datamodel.Relationship.Type relationshipType, long dateTime) throws TskCoreException, TskDataException {
 
-		if (relationshipType.isCreatableFrom(relationshipArtifact) == false) {
+		if (relationshipType.isCreatableFrom(sourceArtifact) == false) {
 			throw new TskDataException("Can not make a " + relationshipType.getDisplayName()
-					+ " relationship from a" + relationshipArtifact.getDisplayName());
+					+ " relationship from a" + sourceArtifact.getDisplayName());
 		}
 
 		/*
-		 * Enforce that all accounts and the relationship between them on from
+		 * Enforce that all accounts and the relationship between them are from
 		 * the same 'source'. This is required for the queries to work
 		 * correctly.
 		 */
@@ -382,17 +388,17 @@ public void addRelationships(AccountFileInstance sender, List<AccountFileInstanc
 
 		if (null != sender) {
 			accountIDs.add(sender.getAccount().getAccountID());
-			if (sender.getDataSourceObjectID() != relationshipArtifact.getDataSourceObjectID()) {
+			if (sender.getDataSourceObjectID() != sourceArtifact.getDataSourceObjectID()) {
 				throw new TskDataException("Sender and relationship are from different data sources :"
-						+ "Sender source ID" + sender.getDataSourceObjectID() + " != relationship source ID" + relationshipArtifact.getDataSourceObjectID());
+						+ "Sender source ID" + sender.getDataSourceObjectID() + " != relationship source ID" + sourceArtifact.getDataSourceObjectID());
 			}
 		}
 
 		for (AccountFileInstance recipient : recipients) {
 			accountIDs.add(recipient.getAccount().getAccountID());
-			if (recipient.getDataSourceObjectID() != relationshipArtifact.getDataSourceObjectID()) {
+			if (recipient.getDataSourceObjectID() != sourceArtifact.getDataSourceObjectID()) {
 				throw new TskDataException("Recipient and relationship are from different data sources :"
-						+ "Recipient source ID" + recipient.getDataSourceObjectID() + " != relationship source ID" + relationshipArtifact.getDataSourceObjectID());
+						+ "Recipient source ID" + recipient.getDataSourceObjectID() + " != relationship source ID" + sourceArtifact.getDataSourceObjectID());
 			}
 		}
 
@@ -403,12 +409,12 @@ public void addRelationships(AccountFileInstance sender, List<AccountFileInstanc
 			try {
 				UnorderedAccountPair accountPair = iter.next();
 				addAccountsRelationship(accountPair.getFirst(), accountPair.getSecond(),
-						relationshipArtifact, relationshipType, dateTime);
+						sourceArtifact, relationshipType, dateTime);
 			} catch (TskCoreException ex) {
-				LOGGER.log(Level.WARNING, "Could not get timezone for image", ex); //NON-NLS
+                // @@@ This should probably not be caught and instead we stop adding
+				LOGGER.log(Level.WARNING, "Error adding relationship", ex); //NON-NLS
 			}
 		}
-
 	}
 
 	/**
@@ -468,14 +474,14 @@ private Account getOrCreateAccount(Account.Type accountType, String accountUniqu
 
 	/**
 	 * Get the blackboard artifact for the given account type, account ID, and
-	 * source file. Create an artifact and return that, of a matching doesn't
-	 * exists
+	 * source file. Create an artifact if it doesn't already exist.
 	 *
 	 * @param accountType     account type
-	 * @param accountUniqueID accountID
+	 * @param accountUniqueID Unique account ID (such as email address)
+     * @param moduleName        module name that found this instance (for the artifact)
 	 * @param sourceFile		    Source file (for the artifact)
 	 *
-	 * @return blackboard artifact, returns NULL is no matching account found
+	 * @return blackboard artifact for the instance
 	 *
 	 * @throws TskCoreException exception thrown if a critical error occurs
 	 *                          within TSK core
@@ -569,10 +575,12 @@ private BlackboardArtifact getAccountFileInstanceArtifact(Account.Type accountTy
 	 * @throws TskCoreException If an error occurs accessing the case database.
 	 *
 	 */
-	public Account.Type getAccountType(String accountTypeName) throws TskCoreException {
+    // NOTE: Full name given for Type for doxygen linking
+	public org.sleuthkit.datamodel.Account.Type getAccountType(String accountTypeName) throws TskCoreException {
 		if (this.typeNameToAccountTypeMap.containsKey(accountTypeName)) {
 			return this.typeNameToAccountTypeMap.get(accountTypeName);
 		}
+        
 		CaseDbConnection connection = db.getConnection();
 		db.acquireSingleUserCaseReadLock();
 		Statement s = null;
@@ -693,7 +701,8 @@ private void addAccountsRelationship(long account1_id, long account2_id, Blackbo
 	}
 
 	/**
-	 * Returns a list of AccountDeviceInstances that have any relationships.
+	 * Returns a list of AccountDeviceInstances that at least one relationship that meets
+     * the criteria listed in the filters.
 	 *
 	 * Applicable filters: DeviceFilter, AccountTypeFilter, DateRangeFilter,
 	 * RelationshipTypeFilter
@@ -798,12 +807,12 @@ public List<AccountDeviceInstance> getAccountDeviceInstancesWithRelationships(Co
 	}
 
 	/**
-	 * Get the number of unique relationship sources found for the given account
-	 * device instance.
-	 *
+	 * Get the number of unique relationship sources (such as EMAIL artifacts) associated with
+     * an account on a given device (AccountDeviceInstance) that meet the filter criteria.
+     *
 	 * Applicable filters: RelationshipTypeFilter, DateRangeFilter
 	 *
-	 * @param accountDeviceInstance Account Device.
+	 * @param accountDeviceInstance Account of interest
 	 * @param filter                Filters to apply.
 	 *
 	 * @return number of account relationships found for this account.
@@ -856,8 +865,8 @@ public long getRelationshipSourcesCount(AccountDeviceInstance accountDeviceInsta
 	}
 
 	/**
-	 * Get the unique relationship sources found for the given account device
-	 * instances.
+     * Get the unique relationship sources (such as EMAIL artifacts) associated with an
+     * account on a given device (AccountDeviceInstance) that meet the filter criteria.
 	 *
 	 * Applicable filters: RelationshipTypeFilter, DateRangeFilter
 	 *