From ee01a67e061a6e83fc8d8c72f76cc360388eafdb Mon Sep 17 00:00:00 2001
From: Jon Siwek <jsiwek@illinois.edu>
Date: Fri, 11 Oct 2013 13:27:04 -0500
Subject: [PATCH] Improve Broxygen end-of-sentence detection.

This is used to display short summaries for things based on the first
sentence in the comments for it, but wouldn't work well when e.g. a
filename is used there.
---
 doc/scripts/example.bro                       |  4 ++++
 src/BroDocObj.cc                              | 23 ++++++++++++++++++-
 .../autogen-reST-enums.rst                    |  6 ++---
 .../doc.autogen-reST-example/example.rst      | 13 +++++++++--
 4 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/doc/scripts/example.bro b/doc/scripts/example.bro
index 2ff12bfa27..505b68e56b 100644
--- a/doc/scripts/example.bro
+++ b/doc/scripts/example.bro
@@ -167,6 +167,10 @@ export {
     # it's fine if the type is inferred, that information is self-documenting
     global var_without_explicit_type = "this works";
 
+	## The first.sentence for the summary text ends here.  And this second
+	## sentence doesn't show in the short description.
+	global dummy: string;
+
     ############## functions/events ############
 
     ## Summarize purpose of "a_function" here.
diff --git a/src/BroDocObj.cc b/src/BroDocObj.cc
index 4316b3113a..649c9c846d 100644
--- a/src/BroDocObj.cc
+++ b/src/BroDocObj.cc
@@ -74,6 +74,27 @@ int BroDocObj::LongestShortDescLen() const
 	return max;
 	}
 
+static size_t end_of_first_sentence(string s)
+	{
+	size_t rval = 0;
+
+	while ( (rval = s.find_first_of('.', rval)) != string::npos )
+		{
+		if ( rval == s.size() - 1 )
+			// Period is at end of string.
+			return rval;
+
+		if ( isspace(s[rval + 1]) )
+			// Period has a space after it.
+			return rval;
+
+		// Period has some non-space character after it, keep looking.
+		++rval;
+		}
+
+	return rval;
+	}
+
 void BroDocObj::FormulateShortDesc()
 	{
 	if ( ! reST_doc_strings )
@@ -87,7 +108,7 @@ void BroDocObj::FormulateShortDesc()
 		{
 		// The short description stops at the first sentence or the
 		// first empty comment.
-		size_t end = it->find_first_of(".");
+		size_t end = end_of_first_sentence(*it);
 
 		if ( end == string::npos )
 			{
diff --git a/testing/btest/Baseline/doc.autogen-reST-enums/autogen-reST-enums.rst b/testing/btest/Baseline/doc.autogen-reST-enums/autogen-reST-enums.rst
index 7ee7d86e66..c20ea7e602 100644
--- a/testing/btest/Baseline/doc.autogen-reST-enums/autogen-reST-enums.rst
+++ b/testing/btest/Baseline/doc.autogen-reST-enums/autogen-reST-enums.rst
@@ -20,11 +20,11 @@ Options
 
 Types
 #####
-======================================= ======================================
-:bro:type:`TestEnum1`: :bro:type:`enum` There's tons of ways an enum can look.
+======================================= ========================================
+:bro:type:`TestEnum1`: :bro:type:`enum` There's tons of ways an enum can look...
 
 :bro:type:`TestEnum2`: :bro:type:`enum` The final comma is optional
-======================================= ======================================
+======================================= ========================================
 
 Redefinitions
 #############
diff --git a/testing/btest/Baseline/doc.autogen-reST-example/example.rst b/testing/btest/Baseline/doc.autogen-reST-example/example.rst
index 2cb75a6b9f..64fb4cb06d 100644
--- a/testing/btest/Baseline/doc.autogen-reST-example/example.rst
+++ b/testing/btest/Baseline/doc.autogen-reST-example/example.rst
@@ -40,13 +40,15 @@ Options
 
 State Variables
 ###############
-=========================================================================== =======================================
+=========================================================================== ==================================================
 :bro:id:`Example::a_var`: :bro:type:`bool`                                  put some documentation for "a_var" here
 
 :bro:id:`Example::var_with_attr`: :bro:type:`count` :bro:attr:`&persistent`
 
 :bro:id:`Example::var_without_explicit_type`: :bro:type:`string`
-=========================================================================== =======================================
+
+:bro:id:`Example::dummy`: :bro:type:`string`                                The first.sentence for the summary text ends here.
+=========================================================================== ==================================================
 
 Types
 #####
@@ -156,6 +158,13 @@ State Variables
    :Type: :bro:type:`string`
    :Default: ``"this works"``
 
+.. bro:id:: Example::dummy
+
+   :Type: :bro:type:`string`
+
+   The first.sentence for the summary text ends here.  And this second
+   sentence doesn't show in the short description.
+
 Types
 #####
 .. bro:type:: Example::SimpleEnum