From aa525935d6a243a613850343936fadb3d97534f2 Mon Sep 17 00:00:00 2001
From: Ge Wang
Date: Fri, 13 Oct 2023 22:56:10 -0700
Subject: [PATCH] ckdoc trailing punctuation
---
src/core/chuck_dl.cpp | 2 --
src/core/chuck_io.cpp | 6 +++---
src/core/chuck_type.cpp | 6 +++---
src/core/ugen_xxx.cpp | 2 +-
src/core/ulib_ai.cpp | 4 ++--
src/core/ulib_ai.h | 4 ++--
src/core/ulib_doc.cpp | 10 +++++-----
src/core/ulib_math.cpp | 2 +-
src/core/ulib_opsc.cpp | 2 +-
src/core/ulib_std.cpp | 2 +-
src/core/util_string.cpp | 41 +++++++++++++++++++++++++++++++++++++++-
src/core/util_string.h | 5 ++++-
12 files changed, 63 insertions(+), 23 deletions(-)
diff --git a/src/core/chuck_dl.cpp b/src/core/chuck_dl.cpp
index cb2dc7a39..06998d6bc 100644
--- a/src/core/chuck_dl.cpp
+++ b/src/core/chuck_dl.cpp
@@ -782,12 +782,10 @@ t_CKBOOL CK_DLL_CALL ck_add_example( Chuck_DL_Query * query, const char * ex )
// set current function documentation
t_CKBOOL CK_DLL_CALL ck_doc_func( Chuck_DL_Query * query, const char * doc )
{
-// #ifdef CK_DOC // disable unless CK_DOC
if(query->curr_func)
query->curr_func->doc = doc;
else
return FALSE;
-// #endif // CK_DOC
return TRUE;
}
diff --git a/src/core/chuck_io.cpp b/src/core/chuck_io.cpp
index 73dcd1e9d..a45139293 100644
--- a/src/core/chuck_io.cpp
+++ b/src/core/chuck_io.cpp
@@ -6642,17 +6642,17 @@ t_CKBOOL init_class_serialio( Chuck_Env * env )
// add getByte
func = make_new_mfun("int", "getByte", serialio_getByte);
- func->doc = "get next requested byte. ";
+ func->doc = "get next requested byte.";
if( !type_engine_import_mfun( env, func ) ) goto error;
// add getBytes
func = make_new_mfun("int[]", "getBytes", serialio_getBytes);
- func->doc = "get next requested number of bytes. ";
+ func->doc = "get next requested number of bytes.";
if( !type_engine_import_mfun( env, func ) ) goto error;
// add getInts
func = make_new_mfun("int[]", "getInts", serialio_getInts);
- func->doc = "get next requested number of integers. ";
+ func->doc = "get next requested number of integers.";
if( !type_engine_import_mfun( env, func ) ) goto error;
// add writeByte
diff --git a/src/core/chuck_type.cpp b/src/core/chuck_type.cpp
index 5f51555af..0fe7366ab 100644
--- a/src/core/chuck_type.cpp
+++ b/src/core/chuck_type.cpp
@@ -9117,7 +9117,7 @@ void Chuck_Type::apropos_top( std::string & output, const std::string & PREFIX )
sout << endl;
// description
if( this->doc != "" )
- sout << PREFIX << " |- " << capitalize(this->doc) << "" << endl;
+ sout << PREFIX << " |- " << capitalize_and_periodize(this->doc) << "" << endl;
// inheritance
if( type->parent != NULL )
{
@@ -9202,7 +9202,7 @@ void apropos_func( std::ostringstream & sout, Chuck_Func * theFunc,
// close paren
sout << ");" << endl;
// output doc
- if( theFunc->doc != "" ) sout << PREFIX << " " << capitalize(theFunc->doc) << endl;
+ if( theFunc->doc != "" ) sout << PREFIX << " " << capitalize_and_periodize(theFunc->doc) << endl;
}
@@ -9336,7 +9336,7 @@ void apropos_var( std::ostringstream & sout, Chuck_Value * var,
sout << var->name << ";" << endl;
// output doc
- if( var->doc != "" ) sout << PREFIX << " " << capitalize(var->doc) << endl;
+ if( var->doc != "" ) sout << PREFIX << " " << capitalize_and_periodize(var->doc) << endl;
}
diff --git a/src/core/ugen_xxx.cpp b/src/core/ugen_xxx.cpp
index e7bdb82c7..adcf48c24 100644
--- a/src/core/ugen_xxx.cpp
+++ b/src/core/ugen_xxx.cpp
@@ -851,7 +851,7 @@ DLL_QUERY xxx_query( Chuck_DL_Query * QUERY )
// add cget: valueAt
func = make_new_mfun( "float", "valueAt", sndbuf_cget_valueAt );
func->add_arg( "int", "pos" );
- func->doc = "get sample value at given position (in samples). ";
+ func->doc = "get sample value at given position (in samples).";
if( !type_engine_import_mfun( env, func ) ) goto error;
// end import
diff --git a/src/core/ulib_ai.cpp b/src/core/ulib_ai.cpp
index 8080f5f85..e3d88d39a 100644
--- a/src/core/ulib_ai.cpp
+++ b/src/core/ulib_ai.cpp
@@ -68,10 +68,10 @@
// [6] http://smirk.cs.princeton.edu/
// sMIRk | Small Music Information Retrieval toolKit
//
-// [7] Tzanetakis, G. and P. R. Cook. 2000 "MARSYAS: A Framework for Audio
+// [7] Tzanetakis, G. and P. R. Cook. 2000. "MARSYAS: A Framework for Audio
// Analysis." Organised Sound. 4:(3)
//
-// [8] Tzanetakis, G. and P. R. Cook. 2002 "Musical Genre Classification of
+// [8] Tzanetakis, G. and P. R. Cook. 2002. "Musical Genre Classification of
// Audio Signals." IEEE Transaction on Speech and Audio Processing. 10(5).
//
// [9] Wang, G., R. Fiebrink, P. R. Cook. 2007. "Combining Analysis and
diff --git a/src/core/ulib_ai.h b/src/core/ulib_ai.h
index 70bbfa8b8..6782dd384 100644
--- a/src/core/ulib_ai.h
+++ b/src/core/ulib_ai.h
@@ -68,10 +68,10 @@
// [6] http://smirk.cs.princeton.edu/
// sMIRk | Small Music Information Retrieval toolKit
//
-// [7] Tzanetakis, G. and P. R. Cook. 2000 "MARSYAS: A Framework for Audio
+// [7] Tzanetakis, G. and P. R. Cook. 2000. "MARSYAS: A Framework for Audio
// Analysis." Organised Sound. 4:(3)
//
-// [8] Tzanetakis, G. and P. R. Cook. 2002 "Musical Genre Classification of
+// [8] Tzanetakis, G. and P. R. Cook. 2002. "Musical Genre Classification of
// Audio Signals." IEEE Transaction on Speech and Audio Processing. 10(5).
//
// [9] Wang, G., R. Fiebrink, P. R. Cook. 2007. "Combining Analysis and
diff --git a/src/core/ulib_doc.cpp b/src/core/ulib_doc.cpp
index c1d9d6438..b536c35ef 100644
--- a/src/core/ulib_doc.cpp
+++ b/src/core/ulib_doc.cpp
@@ -391,7 +391,7 @@ class CKDocHTMLOutput : public CKDocOutput
if(type->doc.size() > 0)
{
- std::string doc = capitalize(type->doc);
+ std::string doc = capitalize_and_periodize(type->doc);
m_outputStr += "" + doc + "
\n";
}
else
@@ -478,7 +478,7 @@ class CKDocHTMLOutput : public CKDocOutput
m_outputStr += "" + var->name + "
";
if(var->doc.size() > 0)
- m_outputStr += "" + capitalize(var->doc) + "
\n";
+ m_outputStr += "" + capitalize_and_periodize(var->doc) + "
\n";
else
m_outputStr += "No description available
\n";
@@ -503,7 +503,7 @@ class CKDocHTMLOutput : public CKDocOutput
m_outputStr += "" + var->name + "
";
if(var->doc.size() > 0)
- m_outputStr += "" + capitalize(var->doc) + "
\n";
+ m_outputStr += "" + capitalize_and_periodize(var->doc) + "
\n";
else
m_outputStr += "No description available
\n";
@@ -537,7 +537,7 @@ class CKDocHTMLOutput : public CKDocOutput
m_outputStr += ")\n";
if(m_func->doc.size() > 0)
- m_outputStr += "" + capitalize(m_func->doc) + "
\n";
+ m_outputStr += "" + capitalize_and_periodize(m_func->doc) + "
\n";
else
m_outputStr += "No description available
\n";
@@ -573,7 +573,7 @@ class CKDocHTMLOutput : public CKDocOutput
m_outputStr += ")\n";
if(m_func->doc.size() > 0)
- m_outputStr += "" + capitalize(m_func->doc) + "
\n";
+ m_outputStr += "" + capitalize_and_periodize(m_func->doc) + "
\n";
else
m_outputStr += "No description available
\n";
diff --git a/src/core/ulib_math.cpp b/src/core/ulib_math.cpp
index 06b7d9a57..38c47fd9b 100644
--- a/src/core/ulib_math.cpp
+++ b/src/core/ulib_math.cpp
@@ -133,7 +133,7 @@ DLL_QUERY libmath_query( Chuck_DL_Query * QUERY )
QUERY->add_sfun( QUERY, atan2_impl, "float", "atan2" );
QUERY->add_arg( QUERY, "float", "y" );
QUERY->add_arg( QUERY, "float", "x" );
- QUERY->doc_func( QUERY, "Compute arc tangent of two variables (y/x). " );
+ QUERY->doc_func( QUERY, "Compute arc tangent of two variables (y/x)." );
// sinh
QUERY->add_sfun( QUERY, sinh_impl, "float", "sinh" );
diff --git a/src/core/ulib_opsc.cpp b/src/core/ulib_opsc.cpp
index 1fb75583d..7a452d8d9 100644
--- a/src/core/ulib_opsc.cpp
+++ b/src/core/ulib_opsc.cpp
@@ -358,7 +358,7 @@ class OscInServer
// TODO
}
- // add OSC method, e.g,. "/foo/frequency"
+ // add OSC method, e.g., "/foo/frequency"
void addMethod( const std::string & method, OscIn * obj )
{
// message to server
diff --git a/src/core/ulib_std.cpp b/src/core/ulib_std.cpp
index 123c90b34..d6fd9fec8 100644
--- a/src/core/ulib_std.cpp
+++ b/src/core/ulib_std.cpp
@@ -255,7 +255,7 @@ DLL_QUERY libstd_query( Chuck_DL_Query * QUERY )
// add ftoi
QUERY->add_sfun( QUERY, ftoi_impl, "int", "ftoi" ); //! float to int
QUERY->add_arg( QUERY, "float", "f" );
- QUERY->doc_func( QUERY, "convert float to integer. " );
+ QUERY->doc_func( QUERY, "convert float to integer." );
// add getenv
QUERY->add_sfun( QUERY, getenv_impl, "string", "getenv" ); //! fetch environment variable
diff --git a/src/core/util_string.cpp b/src/core/util_string.cpp
index abe0ae30e..65217cdd1 100644
--- a/src/core/util_string.cpp
+++ b/src/core/util_string.cpp
@@ -167,7 +167,7 @@ string toupper( const string & str )
//-----------------------------------------------------------------------------
// name: capitalize()
-// capitalize first character
+// desc: capiitalize first character
//-----------------------------------------------------------------------------
string capitalize( const string & s )
{
@@ -183,6 +183,45 @@ string capitalize( const string & s )
+//-----------------------------------------------------------------------------
+// name: capitalize_and_periodize()
+// desc: capiitalize first character and ensure trailing period
+//-----------------------------------------------------------------------------
+string capitalize_and_periodize( const string & s )
+{
+ // copy
+ string retval = capitalize( trim(s) );
+ // check
+ if( retval.length() > 0 )
+ {
+ char c = retval[retval.length()-1];
+ // check for other punctuation
+ switch( c )
+ {
+ case '.':
+ case ',':
+ case '!':
+ case '?':
+ case ')':
+ case '(':
+ case '#':
+ case '\'':
+ case '\"':
+ case '\n':
+ break;
+
+ // in all other cases, append .
+ default:
+ retval += '.';
+ }
+ }
+ // done
+ return retval;
+}
+
+
+
+
//-----------------------------------------------------------------------------
// name: trim()
// desc: return a whitespace (spaces and tabs)-trimmed string
diff --git a/src/core/util_string.h b/src/core/util_string.h
index cc37a06c2..ca897ddda 100644
--- a/src/core/util_string.h
+++ b/src/core/util_string.h
@@ -61,9 +61,12 @@ std::string ltrim( const std::string & val );
// right trim
std::string rtrim( const std::string & val );
-// return capitalized copy of a string
+// return capitalized copy of string
std::string capitalize( const std::string & s );
+// return capiitalized copy of string with trailing punc, adding . as needed
+std::string capitalize_and_periodize( const std::string & s );
+
// replace tabs
std::string replace_tabs( const std::string & s,
char replaceEachTabWithThis );