add some code comments documenting some decisions taken here

cc @beikov

hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java

@@ -762,6 +762,11 @@ public abstract class Dialect implements ConversionContext {
 	 * <li> year(arg)					- synonym of extract(year from a)
 	 * </ul>
 	 *
+	 * Note that according to this definition, the second() function returns
+	 * a floating point value, contrary to the integer type returned by the
+	 * native function with this name on many databases. Thus, we don't just
+	 * naively map these HQL functions to the native SQL functions with the
+	 * same names.
 	 */
 	public void initializeFunctionRegistry(QueryEngine queryEngine) {
 		final BasicTypeRegistry basicTypeRegistry = queryEngine.getTypeConfiguration().getBasicTypeRegistry();

hibernate-core/src/main/java/org/hibernate/dialect/MySQLDialect.java

@@ -527,6 +527,14 @@ public class MySQLDialect extends Dialect {
 		return getMySQLVersion().isBefore( 5, 7 ) ? super.currentTimestamp() : "current_timestamp(6)";
 	}
 
+	// for consistency, we could do this: but I decided not to
+	// because it seems to me that fractional seconds can't possibly
+	// be meaningful in a time, as opposed to a timestamp
+//	@Override
+//	public String currentTime() {
+//		return getMySQLVersion().isBefore( 5, 7 ) ? super.currentTimestamp() : "current_time(6)";
+//	}
+
 	/**
 	 * {@code microsecond} is the smallest unit for
 	 * {@code timestampadd()} and {@code timestampdiff()},

hibernate-core/src/main/java/org/hibernate/dialect/function/CommonFunctionFactory.java

@@ -923,6 +923,11 @@ public class CommonFunctionFactory {
 				new CaseWhenEveryAnyEmulation( queryEngine.getTypeConfiguration(), false ) );
 	}
 
+	/**
+	 * Note that we include these for completeness, but
+	 * since their names collide with the HQL abbreviations
+	 * for extract(), they can't actually be called from HQL.
+	 */
 	public static void yearMonthDay(QueryEngine queryEngine) {
 		final BasicType<Integer> integerType = queryEngine.getTypeConfiguration().getBasicTypeRegistry()
 				.resolve( StandardBasicTypes.INTEGER );
@@ -943,6 +948,11 @@ public class CommonFunctionFactory {
 				.register();
 	}
 
+	/**
+	 * Note that we include these for completeness, but
+	 * since their names collide with the HQL abbreviations
+	 * for extract(), they can't actually be called from HQL.
+	 */
 	public static void hourMinuteSecond(QueryEngine queryEngine) {
 		final BasicType<Integer> integerType = queryEngine.getTypeConfiguration().getBasicTypeRegistry()
 				.resolve( StandardBasicTypes.INTEGER );