BUG#25687226 BUG#28576667 Misc API Help Updates

BUG#25687226 CANNOT FIND GLOBAL SESSION DOCUMENTATION IN SHELL JS API REFERENCE MANUAL

The documentation was updated as follows:
- The db object description was fixed to indicate it is available only on sessions with
  the X protocol. The db object now properly links the Schema help page.
- An annotation was added for the session object, including links to the Session and
  ClassicSession objects as well as a link to shell.connect where the global session can
  be established.

BUG#28576667 SHELL MYSQL MODULE (CLASSICSESSION) API DOCUMENTATION OUTDATED

The class had a hardcoded JavaScript example for both Python and JavaScript documentation
that was using methods that no longer exist. This was fixed by replacing the hardcoded
example with snippets taken from the Unit Tests for the corresponding language.

Change-Id: I7324a2373ed5bef14e46153897120aadc88733c0

Author: rennox

doc/apis/DoxygenLayout.scripting.xml

@@ -19,7 +19,7 @@
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="examples" visible="yes" title="" intro=""/>
+    <tab type="examples" visible="no" title="" intro=""/>
   </navindex>
 
   <!-- Layout definition for a class page -->

doc/apis/connection_data.dox

@@ -29,32 +29,7 @@ On the API exposed on the MySQL Shell, several functions require some connection
 
 \copydoc connection_options
 
-$(TOPIC_CONNECTION_OPTION_SCHEME)
-
-$(TOPIC_CONNECTION_OPTION_SCHEME1)
-
-$(TOPIC_CONNECTION_OPTION_SCHEME2)
-
-$(TOPIC_CONNECTION_OPTION_SCHEME3)
-
-$(TOPIC_CONNECTION_OPTION_SOCKET)
-
-$(TOPIC_CONNECTION_OPTION_SOCKET1)
-
-$(TOPIC_CONNECTION_OPTION_SOCKET2)
-
-$(TOPIC_CONNECTION_OPTION_SOCKET3)
-$(TOPIC_CONNECTION_OPTION_SOCKET_UNIX)
-$(TOPIC_CONNECTION_OPTION_SOCKET_UNIX1)
-$(TOPIC_CONNECTION_OPTION_SOCKET_UNIX2)
-$(TOPIC_CONNECTION_OPTION_SOCKET_UNIX3)
-$(TOPIC_CONNECTION_OPTION_SOCKET_UNIX4)
-$(TOPIC_CONNECTION_OPTION_SOCKET_UNIX5)
-
-@note On Windows, socket needs to be prepended with <b>@\\\\.\\</b>:
-$(TOPIC_CONNECTION_OPTION_SOCKET_WIN)
-$(TOPIC_CONNECTION_OPTION_SOCKET_WIN1)
-@par
+$(TOPIC_CONNECTION_TYPES)
 
 $(TOPIC_CONNECTION_OPTION_SSL_MODE)
 

doc/apis/doxygen.cfg.in

@@ -54,7 +54,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "MySQL Shell"
+PROJECT_NAME           = "MySQL Shell API"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version

doc/apis/main.dox

@@ -27,13 +27,16 @@ The functionality of the APIs is exposed through modules and global objects whic
   - The \ref mysql module contains a lightweight development API to interact with MySQL Servers using a classic session.
   - The <a class ="el" href="classmysqlsh_1_1dba_1_1_dba.html">dba</a> global object enables you to administer InnoDB clusters using the AdminAPI.
   - The <a class ="el" href="classmysqlsh_1_1_shell.html">shell</a> global object gives access to general purpose functions and properties.
-  - The <b>session</b> global object is available when a global session is established.
-  - The <b>db</b> global object is available when the global session is established using a default database.
+  - The <b>session</b><sup>1</sup> global object is available when a global session is established.
+  - The <a class ="el" href="classmysqlsh_1_1mysqlx_1_1_schema.html">db</a> global object is available when the global session is established through the X protocol using a default database.
   - The \ref util global object that groups miscellaneous tools like upgrade checker and JSON import.
 \if DOXYGEN_JS
   - The <a class ="el" href="classmysqlsh_1_1_sys.html">sys</a> global object gives access to system specific parameters.
 \endif
 
+<sup>1</sup> The <b>session</b> global object might be either a <a class ="el" href="classmysqlsh_1_1mysql_1_1_classic_session.html">ClassicSession</a> or a <a class ="el" href="classmysqlsh_1_1mysqlx_1_1_session.html">Session</a> object depending on whether the global session was established using classic MySQL protocol or X protocol respectively.
+For additional details look at the connect function in the <a class ="el" href="classmysqlsh_1_1_shell.html">shell</a> object.
+
 For more information on the functionality these APIs provide see the following documentation:
 
   - The <a class ="el" href="http://dev.mysql.com/doc/refman/5.7/en/document-store.html">Using MySQL as a Document Store</a> documentation explains how to use X DevAPI to achieve a NoSQL-like MySQL database.  

doc/apis/parameter_binding.dox

@@ -12,19 +12,19 @@ Available on SQL strings, allows removing values from expression through the use
 
 \if DOXYGEN_JS
 \code{.js}
-nodeSession = mysqlx.getNodeSession('mike:s3cr3t!@localhost:33060')
+session = mysqlx.getSession('mike:s3cr3t!@localhost:33060')
 
 # Loads the adult customers whose name starts with S
-result = nodeSession.sql('select * from test.customers where name like ? and age < ?').bind('S%').bind(18).execute()
+result = session.sql('select * from test.customers where name like ? and age < ?').bind('S%').bind(18).execute()
 
 The bind function must be called for each place holder on the expression, otherwise an error will occur.
 \endcode
 \elseif DOXYGEN_PY
 \code{.py}
-nodeSession = mysqlx.get_node_session('mike:s3cr3t!@localhost:33060')
+session = mysqlx.get_session('mike:s3cr3t!@localhost:33060')
 
 # Loads the adult customers whose name starts with S
-result = nodeSession.sql('select * from test.customers where name like ? and age < ?').bind('S%').bind(18).execute()
+result = session.sql('select * from test.customers where name like ? and age < ?').bind('S%').bind(18).execute()
 
 The bind function must be called for each place holder on the expression, otherwise an error will occur.
 \endcode

modules/mod_mysql_session.cc

@@ -56,9 +56,7 @@ REGISTER_HELP(CLASSICSESSION_GLOBAL_BRIEF,
 REGISTER_HELP(CLASSICSESSION_BRIEF,
               "Enables interaction with a MySQL Server "
               "using the MySQL Protocol.");
-REGISTER_HELP(CLASSICSESSION_DETAIL,
-              "Provides facilities to execute queries "
-              "and retrieve database objects.");
+REGISTER_HELP(CLASSICSESSION_DETAIL, "Provides facilities to execute queries.");
 ClassicSession::ClassicSession() { init(); }
 
 ClassicSession::ClassicSession(const ClassicSession &session)

modules/mod_mysql_session.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License, version 2.0,
@@ -54,22 +54,17 @@ class Connection;
  * $(CLASSICSESSION_BRIEF)
  *
  * $(CLASSICSESSION_DETAIL)
- *
- * \code{.js}
- * // Establishes the connection.
- * var mysql = require('mysql');
- * var session = mysql.getClassicSession("myuser@localhost", pwd);
- *
- * // Getting a schema through the getSchema function
- * var schema = session.getSchema("sakila");
- *
- * // Getting a schema through a session property
- * var schema = session.sakila;
- * \endcode
- *
- * \sa mysql.getClassicSession(String connectionData, String password)
- * \sa mysql.getClassicSession(Map connectionData, String password)
  */
+#if DOXYGEN_JS
+/**
+ * \snippet mysql_session.js ClassicSession: SQL execution example
+ */
+#elif DOXYGEN_PY
+/**
+ * \snippet mysql_session.py ClassicSession: SQL execution example
+ */
+#endif
+
 class SHCORE_PUBLIC ClassicSession
     : public ShellBaseSession,
       public std::enable_shared_from_this<ClassicSession> {