Move byLine to FileGen.h, add explanatory note

Summary: There's a bit of a gotcha here, let's provide at least a note on this.

Test Plan: Unit tests

Reviewed By: tudorb@fb.com

FB internal diff: D1058244

folly/experimental/FileGen-inl.h

@@ -120,13 +120,19 @@ class FileWriter : public Operator<FileWriter> {
   std::unique_ptr<IOBuf> buffer_;
 };
 
-}  // namespace detail
-
-inline auto byLine(File file, char delim='\n') ->
-decltype(fromFile(std::move(file)) | eachAs<StringPiece>() | resplit(delim)) {
-  return fromFile(std::move(file)) | eachAs<StringPiece>() | resplit(delim);
+}  // !detail
+/**
+ * Generator which reads lines from a file.
+ * Note: This produces StringPieces which reference temporary strings which are
+ * only valid during iteration.
+ */
+inline auto byLine(File file, char delim = '\n')
+    -> decltype(fromFile(std::move(file))
+                | eachAs<StringPiece>()
+                | resplit(delim)) {
+  return fromFile(std::move(file))
+       | eachAs<StringPiece>()
+       | resplit(delim);
 }
 
-}  // namespace gen
-}  // namespace folly
-
+}}  // !folly::gen

folly/experimental/FileGen.h

@@ -65,8 +65,7 @@ S toFile(File file, std::unique_ptr<IOBuf> buffer) {
   return S(std::move(file), std::move(buffer));
 }
 
-}  // namespace gen
-}  // namespace folly
+}}  // !folly::gen
 
 #include "folly/experimental/FileGen-inl.h"