Add more documentation for csharp_options.h

This also renames generate_directories to base_namespace_specified; generating directories is the
immediate *effect* of specifying a base namespace, but with this change the options reflect what has been
specified rather than the effect. (There may be other effects in the future, of course.)

2 files changed, 18 insertions, 6 deletions

diff --git a/src/google/protobuf/compiler/csharp/csharp_generator.cc b/src/google/protobuf/compiler/csharp/csharp_generator.cc
index 567f827e..df9730f8 100644
--- a/src/google/protobuf/compiler/csharp/csharp_generator.cc
+++ b/src/google/protobuf/compiler/csharp/csharp_generator.cc
@@ -80,7 +80,7 @@ bool Generator::Generate(
       cli_options.file_extension = options[i].second;
     } else if (options[i].first == "base_namespace") {
       cli_options.base_namespace = options[i].second;
-      cli_options.generate_directories = true;
+      cli_options.base_namespace_specified = true;
     } else {
       *error = "Unknown generator option: " + options[i].first;
       return false;
@@ -90,7 +90,7 @@ bool Generator::Generate(
   string filename_error = "";
   std::string filename = GetOutputFile(file,
       cli_options.file_extension,
-      cli_options.generate_directories,
+      cli_options.base_namespace_specified,
       cli_options.base_namespace,
       &filename_error);
 
diff --git a/src/google/protobuf/compiler/csharp/csharp_options.h b/src/google/protobuf/compiler/csharp/csharp_options.h
index d75eefa6..9e5573ca 100644
--- a/src/google/protobuf/compiler/csharp/csharp_options.h
+++ b/src/google/protobuf/compiler/csharp/csharp_options.h
@@ -44,14 +44,26 @@ struct Options {
   Options() :
       file_extension(".cs"),
       base_namespace(""),
-      generate_directories(false) {
+      base_namespace_specified(false) {
   }
   // Extension of the generated file. Defaults to ".cs"
   string file_extension;
-  // Base namespace to use to create directory hierarchy. Defaults to ""
+  // Base namespace to use to create directory hierarchy. Defaults to "".
+  // This option allows the simple creation of a conventional C# file layout,
+  // where directories are created relative to a project-specific base
+  // namespace. For example, in a project with a base namespace of PetShop, a
+  // proto of user.proto with a C# namespace of PetShop.Model.Shared would
+  // generate Model/Shared/User.cs underneath the specified --csharp_out
+  // directory.
+  //
+  // If no base namespace is specified, all files are generated in the
+  // --csharp_out directory, with no subdirectories created automatically.
   string base_namespace;
-  // Whether or not to generate directory hierarchy. Defaults to false
-  bool generate_directories;
+  // Whether the base namespace has been explicitly specified by the user.
+  // This is required as the base namespace can be explicitly set to the empty
+  // string, meaning "create a full directory hierarchy, starting from the first
+  // segment of the namespace."
+  bool base_namespace_specified;
 };
 
 }  // namespace csharp