diff --git a/src/build_settings.cpp b/src/build_settings.cpp
index 41849fd6b..c12107bf7 100644
--- a/src/build_settings.cpp
+++ b/src/build_settings.cpp
@@ -250,9 +250,10 @@ gb_global char const *odin_command_strings[32] = {
 
 
 enum CmdDocFlag : u32 {
-	CmdDocFlag_Short       = 1<<0,
-	CmdDocFlag_AllPackages = 1<<1,
-	CmdDocFlag_DocFormat   = 1<<2,
+	CmdDocFlag_Short         = 1<<0,
+	CmdDocFlag_InSourceOrder = 1<<1,
+	CmdDocFlag_AllPackages   = 1<<2,
+	CmdDocFlag_DocFormat     = 1<<3,
 };
 
 enum TimingsExportFormat : i32 {
@@ -2637,4 +2638,3 @@ gb_internal bool init_build_paths(String init_filename) {
 
 	return true;
 }
-
diff --git a/src/docs.cpp b/src/docs.cpp
index 004134a5c..09a62562f 100644
--- a/src/docs.cpp
+++ b/src/docs.cpp
@@ -28,7 +28,7 @@ gb_global char const *print_entity_names[Entity_Count] = {
 };
 
 
-gb_internal GB_COMPARE_PROC(cmp_entities_for_printing) {
+gb_internal GB_COMPARE_PROC(cmp_entities_for_printing_by_kind_order) {
 	GB_ASSERT(a != nullptr);
 	GB_ASSERT(b != nullptr);
 	Entity *x = *cast(Entity **)a;
@@ -55,6 +55,37 @@ gb_internal GB_COMPARE_PROC(cmp_entities_for_printing) {
 	return res;
 }
 
+gb_internal GB_COMPARE_PROC(cmp_entities_for_printing_by_order_in_src) {
+	GB_ASSERT(a != nullptr);
+	GB_ASSERT(b != nullptr);
+	Entity *x = *cast(Entity **)a;
+	Entity *y = *cast(Entity **)b;
+	u64 res = 0;
+	if (x->pkg != y->pkg) {
+		if (x->pkg == nullptr) {
+			return -1;
+		}
+		if (y->pkg == nullptr) {
+			return +1;
+		}
+		res = string_compare(x->pkg->name, y->pkg->name);
+		if (res != 0) {
+			return res;
+		}
+	}
+
+	u64 sx = x->order_in_src;
+	u64 sy = y->order_in_src;
+	res = u64_cmp(sx, sy);
+
+	if (res) {
+		return res;
+	}
+	res = i32_cmp(x->token.pos.offset, y->token.pos.offset);
+
+	return res;
+}
+
 gb_internal GB_COMPARE_PROC(cmp_ast_package_by_name) {
 	GB_ASSERT(a != nullptr);
 	GB_ASSERT(b != nullptr);
@@ -237,18 +268,37 @@ gb_internal void print_doc_package(CheckerInfo *info, AstPackage *pkg) {
 			}
 			array_add(&entities, e);
 		}
-		array_sort(entities, cmp_entities_for_printing);
+
+		bool in_src_order = build_context.cmd_doc_flags & CmdDocFlag_InSourceOrder;
+
+		if (in_src_order) {
+			array_sort(entities, cmp_entities_for_printing_by_order_in_src);
+		} else {
+			array_sort(entities, cmp_entities_for_printing_by_kind_order);
+		}
 
 		bool show_docs = (build_context.cmd_doc_flags & CmdDocFlag_Short) == 0;
 
+		AstFile *curr_file = nullptr;
 		EntityKind curr_entity_kind = Entity_Invalid;
 		for (Entity *e : entities) {
-			if (curr_entity_kind != e->kind) {
-				if (curr_entity_kind != Entity_Invalid) {
-					print_doc_line(0, "");
+			if (in_src_order) {
+				if (curr_file != e->file) {
+					if (curr_file != nullptr) {
+						print_doc_line(0, "");
+					}
+					curr_file = e->file;
+					String filename = remove_directory_from_path(curr_file->fullpath);
+					print_doc_line(1, "file: %s", filename);
+				}
+			} else {
+				if (curr_entity_kind != e->kind) {
+					if (curr_entity_kind != Entity_Invalid) {
+						print_doc_line(0, "");
+					}
+					curr_entity_kind = e->kind;
+					print_doc_line(1, "%s", print_entity_names[e->kind]);
 				}
-				curr_entity_kind = e->kind;
-				print_doc_line(1, "%s", print_entity_names[e->kind]);
 			}
 
 			Ast *type_expr = nullptr;
@@ -303,7 +353,6 @@ gb_internal void print_doc_package(CheckerInfo *info, AstPackage *pkg) {
 			print_doc_line(2, filename);
 		}
 	}
-
 }
 
 gb_internal void generate_documentation(Checker *c) {
diff --git a/src/main.cpp b/src/main.cpp
index af5a3b0da..d8017e7d3 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -370,6 +370,7 @@ enum BuildFlagKind {
 	BuildFlag_GoToDefinitions,
 
 	BuildFlag_Short,
+	BuildFlag_InSourceOrder,
 	BuildFlag_AllPackages,
 	BuildFlag_DocFormat,
 
@@ -602,6 +603,7 @@ gb_internal bool parse_build_flags(Array<String> args) {
 	add_flag(&build_flags, BuildFlag_SourceCodeLocations, 		str_lit("source-code-locations"), 		BuildFlagParam_String,  Command__does_build);
 
 	add_flag(&build_flags, BuildFlag_Short,                   str_lit("short"),                     BuildFlagParam_None,    Command_doc);
+	add_flag(&build_flags, BuildFlag_InSourceOrder,           str_lit("in-source-order"),           BuildFlagParam_None,    Command_doc);
 	add_flag(&build_flags, BuildFlag_AllPackages,             str_lit("all-packages"),              BuildFlagParam_None,    Command_doc | Command_test | Command_build);
 	add_flag(&build_flags, BuildFlag_DocFormat,               str_lit("doc-format"),                BuildFlagParam_None,    Command_doc);
 
@@ -1491,6 +1493,9 @@ gb_internal bool parse_build_flags(Array<String> args) {
 						case BuildFlag_Short:
 							build_context.cmd_doc_flags |= CmdDocFlag_Short;
 							break;
+						case BuildFlag_InSourceOrder:
+							build_context.cmd_doc_flags |= CmdDocFlag_InSourceOrder;
+							break;
 						case BuildFlag_AllPackages:
 							build_context.cmd_doc_flags |= CmdDocFlag_AllPackages;
 				   			build_context.test_all_packages = true;
@@ -3000,6 +3005,9 @@ gb_internal int print_show_help(String const arg0, String command, String option
 		if (print_flag("-short")) {
 			print_usage_line(2, "Shows shortened documentation for the packages.");
 		}
+		if (print_flag("-in-source-order")) {
+			print_usage_line(2, "Shows documentation for the packages in source order within each file.");
+		}
 	}
 
 	if (check) {
@@ -3279,7 +3287,7 @@ gb_internal void print_show_unused(Checker *c) {
 		array_add(&unused, e);
 	}
 
-	array_sort(unused, cmp_entities_for_printing);
+	array_sort(unused, cmp_entities_for_printing_by_kind_order);
 
 	print_usage_line(0, "Unused Package Declarations");