[Gardening] Document InputFile

Author: CodaFi

include/swift/Frontend/InputFile.h

@@ -33,6 +33,25 @@ enum class InputFileKind {
 // Inputs may include buffers that override contents, and eventually should
 // always include a buffer.
 class InputFile {
+/// An \c InputFile encapsulates information about an input passed to the
+/// frontend.
+///
+/// Compiler inputs are usually passed on the command line without a leading
+/// flag. However, there are clients that use the \c CompilerInvocation as
+/// a library like LLDB and SourceKit that generate their own \c InputFile
+/// instances programmatically. Note that an \c InputFile need not actually be
+/// backed by a physical file, nor does its file name actually reflect its
+/// contents. \c InputFile has a constructor that will try to figure out the file
+/// type from the file name if none is provided, but many clients that
+/// construct \c InputFile instances themselves may provide bogus file names
+/// with pre-computed kinds. It is imperative that \c InputFile::getType be used
+/// as a source of truth for this information.
+///
+/// \warning \c InputFile takes an unfortunately lax view of the ownership of
+/// its primary data. It currently only owns the file name and a copy of any
+/// assigned \c PrimarySpecificPaths outright. It is the responsibility of the
+/// caller to ensure that an associated memory buffer outlives the \c InputFile.
+class InputFile final {
   std::string Filename;
   bool IsPrimary;
   /// Points to a buffer overriding the file's contents, or nullptr if there is