added DOW to flexible search

proto/cmp/types/v1alpha1/dow.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+package cmp.types.v1alpha1;
+
+// DOW
+//
+// DOW means DayOfWeek and is used to determine specific arrival days of the week a customer would like to go on holidays
+// for example only travelling on a Saturday or Sunday.
+// It is also used to express that a show, tour or excursion is only taking place on Sundays. Or that a forthnight
+// Flotilla Sailing starts on Saturday.
+//
+// we are using a bitmask like this:
+//
+// dow = 112
+// the intention is to express Friday, Saturday and Sunday, which is binary 1110000, which computes to DOW=112,
+// like just fri+sat is 110000 which computes to DOW=48 or Monday and Tuesday which computes to DOW=3
+// This is easy to calculate with basic integer mathematics, like for Sunday + Wednesday you sum 64 + 4 = 68,
+// so you set the field to 68.
+//
+// See this table with DOW logic:
+//
+// | DOW      |  Sunday  |  Saturday  |  Friday  |  Thursday  | Wednesday |  Tuesday  |  Monday  |
+// |:--------:|:---------:|:----------:|:--------:|:----------:|:---------:|:---------:|:--------:|
+// | Binary   | 1000000   | 0100000    | 0010000  | 0001000    | 0000100   | 0000010   | 0000001 |
+// | Exponent | 2^6       | 2^5        | 2^4      | 2^3        | 2^2       | 2^1       | 2^0      |
+// | Result   | 64        | 32         | 16       | 8          | 4         | 2         | 1        |
+//
+//
+//
+// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha1/dow.proto.dot.xs.svg)
+// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha1/dow.proto.dot.svg)
+message DayOfWeek {
+  int32 dow = 1;
+}
+
+

proto/cmp/types/v1alpha1/travel_period.proto

@@ -3,23 +3,34 @@ syntax = "proto3";
 package cmp.types.v1alpha1;
 
 import "cmp/types/v1alpha1/date.proto";
+import "cmp/types/v1alpha1/dow.proto";
 
 // Travel Period
 // ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha1/travel_period.proto.dot.xs.svg)
 // [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha1/travel_period.proto.dot.svg)
 message TravelPeriod {
   // Start date of a trip for messages where no Date/Time is required (datetime_range.proto) when the travelling starts.
+  // Most trips will be for an exact start and end date. In that case just these two fields are used. We discourage the use
+  // of only a start date and Length of Stay.
   cmp.types.v1alpha1.Date start_date = 1;
   // End date of a trip for messages where no Date/Time is required (datetime_range.proto) when the travelling ends. 
   // The end date is different when the trip is a one-way from point A to B compared to when the trip is a fortnight
   // holiday and the customers return home on the end date.
   cmp.types.v1alpha1.Date end_date = 2;
-  // Start and end date can be set wider than the desired length of a trip, so that various alternatives can be considered
-  // Ex start date = 1 April, End date is 30 June, stay would be for 7 nights
-  // Setting the boolean to true means that the period between start and end date should be more than the "Length of Stay"
+  // Start and end date can be set wider than the desired length of a trip, so that various alternatives can be considered.
+  // Ex start date = 1 April, End date is 30 June, stay would be for 7 nights.
+  // Setting the boolean to true means that the period between start and end date should be more than the Length of Stay.
+
   bool flexible = 3;
-  // Ex start date = 1 April, End date is 30 June, stay would be for 7 to 7 nights
-  // Ex start date = 1 April, End date is 30 June, stay would be for 7 to 10 nights
+  // Setting the length of the trip in case of a flexible search.
+  // Ex start date = 1 April, End date is 30 June, stay would be for 7 to 7 nights.
+  // Ex start date = 1 April, End date is 30 June, stay would be for 7 to 10 nights.
+  // The arrival and departure must fall between start and end-date.
   int32 los_from_nights = 4;
   int32 los_to_nights = 5;
+  // By adding a DayOfWeek restriction, the number of results can be reduced to the specific arrival days in the interest
+  // of the end-customer who for example only can travel during weekends or at the contrary desires to avoid the crowds
+  // by travelling during weekdays.
+  // a bitmask is being used to express the DOW or DOWs.
+  cmp.types.v1alpha1.DayOfWeek dow = 6;
 }