diff --git a/scripts/reformat_docs.py b/scripts/reformat_docs.py
index 35dc6e12809..eadc5359052 100644
--- a/scripts/reformat_docs.py
+++ b/scripts/reformat_docs.py
@@ -95,6 +95,10 @@ def is_block_valid(self, block):
     def convert_sections(self, block):
         return [self.format_module(block)]
 
+    def needs_new_header(self, file_contents):
+        return (re.search(r'^\/\/\/ \\file$', file_contents, flags=re.MULTILINE)
+                is None)
+
 
 class FunctionFormatter(GenericFormatter):
     def __init__(self, doc_width):
@@ -188,6 +192,7 @@ def convert_sections(self, block):
 
 def replace_block(
         block_contents,
+        file_contents,
         file,
         header_formatter,
         class_formatter,
@@ -199,9 +204,10 @@ def replace_block(
             {f.name: f.contents for f in parse_fields(block_contents.group(1))})
 
     if header_formatter.is_block_valid(block):
-        return '%s%s\n' % (
-                block_contents.group(0),
-                header_formatter.convert(header_from_block(block)))
+        converted = header_formatter.convert(header_from_block(block))
+        if header_formatter.needs_new_header(file_contents) and converted:
+            return block_contents.group(0) + converted + '\n'
+        return block_contents.group(0)
 
     if class_formatter.is_block_valid(block):
         return class_formatter.convert(class_from_block(block))
@@ -231,6 +237,7 @@ def convert_file(file, inplace):
     new_contents = block_re.sub(
             lambda match: replace_block(
                 match,
+                contents,
                 file,
                 header_formatter,
                 class_formatter,