Document return value of get_show_symbol_language function

Because the behaviour could be surprising if the reader is not familiar
with the intended behaviour.

Author: thomasspriggs

src/goto-programs/show_symbol_table.cpp

@@ -26,6 +26,12 @@ Author: Daniel Kroening, kroening@kroening.com
 
 /// \brief Gets the language which should be used for showing the type and value
 ///   of the supplied \p symbol.
+/// \return A unique pointer, pointing to the language corresponding to the mode
+///   of the \p symbol in the case where the symbol specifies a known/registered
+///   language mode. Returns the globally configured default language/first
+///   language registered in the case where mode is empty or does not correspond
+///   to a known registered language. The enables showing the symbol even if the
+///   language is not recognised.
 static std::unique_ptr<languaget>
 get_show_symbol_language(const symbolt &symbol)
 {