This article provides a comprehensive guide to configuring the koroFileHeader VSCode extension, covering comment templates, automatic updates, and various customization options.

Comment Template Settings

Default Configuration

Search for fileheader in your user preferences. The default configurations are:

"fileheader.customMade": {} // File header comment
"fileheader.cursorMode": {} // Function comment

Custom Template

1. In your user settings, search for fileheader.
2. Copy the default configuration and modify it as needed.
3. Restart your editor for the changes to take effect.

After configuring as shown above, the generated comments would look like this:

// File header comment shortcut: Windows: ctrl+alt+i, Mac: ctrl+cmd+i
// Content added before the comment
/*
 * Author       : OBKoro1
 * Date         : 2019-09-24 20:25:33
 * LastEditors  : OBKoro1
 * LastEditTime : 2019-12-16 21:16:08
 * FilePath     : /fileHead/test.js
 * Custom information, cursor automatically moves to Description
 * Handles newlines correctly
 */
// Content added after the comment
// Function comment shortcut: Windows: ctrl+alt+t, Mac: ctrl+cmd+t
/**
 * @description:
 * @param {type}
 * @return:
 */

Automatically Updating Last Edit Time, Editor, and File Path

To enable this functionality, configure the following properties in your settings:

"fileheader.customMade": {
  "Date": "Do not edit", // File creation time (constant)
  "LastEditors": "OBKoro1", // Last editor of the file
  "LastEditTime": "Do not edit", // Last edit time (auto-updates)
  "FilePath": "Do not edit" // Relative path of the file in the project (auto-updates)
}
// Omit corresponding properties to disable them

Pattern Comments

One-click generation of decorative comment patterns is supported, such as the classic "Buddha blesses you with no bugs" ASCII art.

/*
 * ......................................&&.........................
 * ....................................&&&..........................
 * ... (line of arrow pattern) ...
 */

Plugin Configuration

Refer to the template setting method to find the configuration item "fileheader.configObj" and modify this object.

Overview of Features

All features have brief descriptions within the configuration fields. You can read the overall configuration functionality here and then search for the corresponding fields in this document for detailed usage.

Configuration Details

1. Custom Language Comment Symbols (Optional)

User-Defined Comment Symbols

• This configuration is the highest priority and overrides the plugin's built-in comment format for a language.
• Users can set corresponding comment symbols for any language or file type by following the format shown in the example below.
• Useful when a specific library requires a particular comment format for processing.

This ensures the plugin remains functional evenif new languages emerge or project maintenance ceases.

Language Setting

"fileheader.configObj": {
  "language": {
    // Example for JavaScript files
    "js": {
      "head": "/$$",
      "middle": " $ @",
      "end": " $/",
      // Custom function comment symbols (optional)
      "functionSymbol": {
        "head": "/******* ",
        "middle": " * @",
        "end": " */"
      }
    },
    // Match multiple file suffixes at once
    "h/hpp/cpp": {
      "head": "/*** ",
      "middle": " * @",
      "end": " */"
    },
    // Handle files with special requirements, e.g., test.blade.php
    "blade.php": {
      "head": "<!--",
      "middle": " * @",
      "end": "-->"
    }
  }
}

• The property under language can be a file extension or a language identifier (e.g., js or javascript). Using file extensions is recommended for reliability.

Example output for test.java with the above configuration:

/$$
 $ @Author: OBKoro1
 $ @Date: 2019-01-19
 $ @LastEditors: OBKoro1
 $ @LastEditTime: 2019-01-19
 $ @Description: File header comment
 $ @FilePath: /itemName/src/index.js
 $/
/$$
 $ @description: Function comment
 $ @param {type}
 $ @return:
 $/

Matching Multiple File Suffixes Once

/***
 * Author       : OBKoro1
 * Date         : 2019-05-13 15:54:32
 * LastEditors  : OBKoro1
 * LastEditTime : 2020-02-14 22:04:52
 * FilePath     : /fileHead/test.h
 * Description  : C++ h, hpp, and cpp files all use the same comment style.
 **/

Handling Files with Special Requirements

The above blade.php configuration only overrides files ending with .blade.php, without affecting regular .php files. This is useful when a library expects different comment syntax for specific file variations.

Generated comment for test.blade.php:

<!--
 * @Author: OBKoro1
 * @Date: 2019-10-20 16:37:49
 * @LastEditors: OBKoro1
 * @LastEditTime: 2019-10-20 16:49:09
 * @FilePath: /xpdevtool/src/test.blade.php
 * @Description: Description
-->

Default Comment Format

"fileheader.configObj": {
  "annotationStr": {
    "head": "/*",        // Custom comment head
    "middle": " * @",    // Custom comment middle part
    "end": " */",        // Custom comment end
    "use": false          // Whether to use custom comment symbols
  }
}

When use is set to true, the generated comments will be:

/*
 * @Author: OBKoro1
 * @Github: https://github.com/OBKoro1
 * @Date: 2018-12-12 18:50:10
 * @LastEditors: OBKoro1
 * @LastEditTime: 2018-12-13 15:54:05
 * @Description: File header comment
 */
/*
 * @description:
 * @param {type}
 * @return: Function comment
 */

The annotationStr configuration matching logic:

1. Match config.language (user-defined custom symbols).
2. Match the plugin's built-in language support.
3. Fallback to this configuration only if no match is found and use is true.

2. Automatically Add File Header Comment

This option is designed for users who often forget to add header comments. It works best when combined with the header comment blacklist.

"fileheader.configObj": {
  "autoAdd": true // Enabled by default
}

Configuration Logic: When enabled, the plugin checks if the currently saved file has a header comment. If not, it automatically adds the header comment (as if the shortcut was pressed).

The plugin determines a file lacks a header comment if:

1. The first 15 lines do not contain the comment start for the language/custom format.
2. The comment does not contain the four special fields: LastEditors, LastEditTime, FilePath, or Date.
3. If custom special fields are used, the plugin checks for those instead.

Warning: If your template does not include these special fields, do not enable this feature, as it will repeatedly add header comments.

autoAlready: Only Auto-Add for Supported Languages

"fileheader.configObj": {
  "autoAdd": true,
  "autoAlready": true // Enabled by default
}

• Prevents adding comments to files like .json where comments are invalid.
• Prevents using default comment formats for unsupported languages, which might cause issues.
• To enable auto-adding for all files, set autoAlready to false.

White/Blacklist for Auto-Adding

White List (supportAutoLanguage): Only files matching the specified extensions will automatically get header comments.

"fileheader.configObj": {
  "supportAutoLanguage": []
}

Black List (prohibitAutoAdd): Prevents automatic header comments for specified file types.

"fileheader.configObj": {
  "prohibitAutoAdd": ["json", "md"]
}

Project Black List (prohibitItemAutoAdd): Prevents automatic header comments for specific projects (useful for teams opposed to header comments).

"fileheader.configObj": {
  "prohibitItemAutoAdd": ["test_koro", "test_koro2"]
}

• Use the exact project name. The project must be opened with that name as the root directory.

File Size Limit (autoAddLine): Disables auto-adding for files exceeding a certain number of lines.

"fileheader.configObj": {
  "autoAddLine": 100 // Default: over 100 lines, no automatic header comment
}

Folder/File Name Blacklist (folderBlacklist): Prevents adding header comments if the file path matches the specified names.

"fileheader.configObj": {
  "folderBlacklist": ["node_modules", "some/folder/or/file/name"]
}

Auto-Add Only Once (only once): The plugin records file paths that have been auto-added, preventing them from being auto-added again during the current editor session. This prevents infinite loops if a user deletes the auto-added comment.

File Path Configuration (FilePath)

"fileheader.customMade": {
  "Author": "OBKoro1",
  "FilePath": "Do not edit" // Add this line
}

• Automatically updated in version 4.6.0+ to reflect file moves or renames.
• Setting FilePath to "no item name" removes the project name from the path.
• Setting it to "only file name" shows only the file name.
• Setting it to "only file name without ext" shows the filename without extension.
• You can rename the field using specialOptions.
• Useful for projects with deep folder structures or many files with the same name (e.g., multiple index.js files).

Example outputs:

/*
 * FilePath: /foldername/src/index.js // Default with project name
 * FilePath: /src/index.js  // With "no item name"
 * FilePath: index.js  // With "only file name"
 * FilePath: index  // With "only file name without ext"
 */

Modify Path Separator (filePathColon):

"fileheader.configObj": {
  "filePathColon": "\\\\" // Use \\ as separator; escaped
}

Wide Setting for Header Comments (wideSame)

"fileheader.configObj": {
  "wideSame": false, // Set to true to enable
  "wideNum": 13      // Field length, default is 13
}

Enabled Effect (length 13):

/*
 * Author       : OBKoro1
 * Date         : 2019-09-24 20:25:33
 * LastEditors  : OBKoro1
 * LastEditTime : 2019-12-16 21:16:08
 * FilePath     : /fileHead/test.js
 */

Effect with shorter length (9):

/*
 * Author   : OBKoro1
 * Date     : 2019-09-24 20:25:33
 * LastEditors: OBKoro1
 * LastEditTime: 2019-12-17 10:35:19
 * FilePath : /fileHead/test.js
 */

3. Insert Header Comment at Specific Line

"fileheader.configObj": {
  "headInsertLine": {
    "php": 2,   // For .php files, insert at line 2
    "*": 3       // For all other files, insert at line 3
  }
}

• Default is to insert at line 1.
• If the file has fewer lines than specified, the comment is appended at the end.

Example with a two-line PHP file, inserting at line 2:

<?php
/*
 * @Author: OBKoro1
 * @Date: 2018-12-21 10:49:35
 * @LastEditors: OBKoro1
 * @LastEditTime: 2018-12-21 17:06:07
 * @Description:
 */
?>

4. Date Field Time Options

Current Time / File Creation Time

"fileheader.configObj": {
  "createFileTime": true // Set to false for the current comment generation time
}

• For header comments, createFileTime defaults to the file's creation time. Setting it to false uses the current time.
• For function comments (V3.0+), the Date field uses the comment insertion time.

Time Formatting

"fileheader.configObj": {
  "dateFormat": "YYYY-MM-DD HH:mm:ss" // Default format
}

Uses moment.js format tokens. Example:

"dateFormat": "YYYY-MM-DD HH:mm:ss ZZ" // Output: 2019-05-20 15:42:07 +0800

This affects all time fields.

5. Insert Content Before/After Header Comment

Before Header Comment

"fileheader.configObj": {
  "beforeAnnotation": {
    "py": "#!/usr/bin/env python\n# coding=utf-8",
    "*": "\n" // Add an empty line before header comments for all files except .py
  }
}

Result for test.py:

#!/usr/bin/env python
# coding=utf-8
'''
@Author: OBKoro1
@Date: 2019-02-18 13:03:37
@LastEditors: OBKoro1
@LastEditTime: 2019-02-19 12:26:24
'''

After Header Comment

"fileheader.configObj": {
  "afterAnnotation": {
    "js": "// Content after js file header comment",
    "*": "\n" // Add an empty line after header comment for all files except .js
  }
}

6. Customizing Special Field Names

You can rename the plugin's special fields (Date, LastEditTime, LastEditors, Description, FilePath). This is useful for compatibility with static blog generators or other tools that use different field names.

"fileheader.customMade": {
  "Author": "OBKoro1",
  "Date": "Do not edit",
  "LastEditTime": "Do not edit",
  "LastEditors": "Do not edit",
  "FilePath": "Do not edit",
  "Description": ""
},
"fileheader.configObj": {
  "specialOptions": {
    "Date": "since",
    "LastEditTime": "lastTime",
    "LastEditors": "LastAuthor",
    "Description": "message",
    "FilePath": "File relative path"
  }
}

• Default is an empty object (no changes).
• You can modify only specific fields.
• Old special fields in existing comments will still be handled by the plugin. Note: If used in a team, all members must apply the same customizations for automatic updates to work correctly.

Example output:

/*
 * @Author: OBKoro1
 * @since: 2019-05-13 15:54:32
 * @lastTime: 2019-08-08 16:25:22
 * @LastAuthor: Do not edit
 * @File relative path: /testItem/src/index.js
 * @message:
 */

You can also customize parameter/return aliases for function comments:

"param": "paramAlias",
"return": "returnAlias"

7. Outputting Custom Information in Comments

Use the special properties custom_string_obkoro1 to custom_string_obkoro100 within customMade or cursorMode to output custom text. There are also two special fields: custom_string_obkoro1_copyright and custom_string_obkoro1_date.

"fileheader.customMade": {
  "custom_string_obkoro1_date": "Do not edit", // Time without Date prefix
  "Github": "https://github.com/OBKoro1",
  "custom_string_obkoro2": "Any custom information from 1 to 100",
  "Author": "OBKoro1",
  "custom_string_obkoro1_copyright": "Copyright ${now_year} OBKoro1, All Rights Reserved. ",
  "custom_string_obkoro1": "Copyright statements, signatures, blank lines, etc."
}

Example output in test.js:

/**
 * 2020-07-03 14:50:17
 * @Github: https://github.com/OBKoro1
 * custom_string_obkoro1~custom_string_obkoro100 can output custom information
 * @Author: OBKoro1
 * Copyright 2020 OBKoro1, All Rights Reserved
 * Copyright statements, signatures, blank lines, etc.
 */

8. Adding Comment Symbols on Newlines

When a custom field value contains a newline character (\n, \r\n, \r), the plugin automatically adds the comment symbol to the beginning of the new line.

Configuration:

"fileheader.customMade": {
  "Author": "OBKoro1",
  "test": "HaHa\nHeHe\r\nHoHo"
}

Result:

/*
 * @Author: OBKoro1
 * @test: HaHa
 * HeHe
 * HoHo
 */

To disable this behavior:

"fileheader.configObj": {
  "switch": {
    "newlineAddAnnotation": true // Enabled by default
  }
}

9. Moving Cursor to Description: Line

"fileheader.configObj": {
  "moveCursor": true // Enabled by default
}

• Automatically moves the cursor to the Description: line after inserting a comment.
• Requires the Description field in customMade or cursorMode.
• You can rename the Description field using specialOptions.

10. Customizing @ and : Symbols

To modify the @ and : characters used in comments:

"fileheader.configObj": {
  "atSymbol": ["@", "@"], // Default: ["@", "@"] for [header, function] comments
  "atSymbolObj": {
    "js": ["", "@"],     // .js files: remove @ from header comments
    "java": ["#", "@"]   // .java files: change @ to # in headers
  },
  "colon": [": ", ": "], // Default: [": ", ": "]
  "colonObj": {
    "js": [" ", ": "],    // .js: replace colon with space in headers
    "java": [": ", "$"]   // .java: change colon to $ in function comments
  }
}

11. Hiding Plugin Error Notifications

"fileheader.configObj": {
  "showErrorMessage": false // Default: hide error notifications
}

12. Error Logging

"fileheader.configObj": {
  "writeLog": false // Default: no error log
}

To set a custom log directory:

1. Open command palette (Ctrl+P).
2. Run >fileheader.errPathSet and select a folder.

13. Diff Check on File Save (Single File)

After each save, performs a diff check. If only LastEditors/LastEditTime have changed, the file is reverted to the latest local commit.

"fileheader.configObj": {
  "CheckFileChange": false // Disabled by default
}

Use Case: Prevents accidental commits when changes are undone but metadata fields remain updated.

Logic:

1. Checks if the root directory has a .git folder.
2. Gets the diff for the saved file.
3. If only the metadata fields changed, reverts the file using a local git checkout.

Safety: This operates on a single file and results can be undone with a single undo in the editor.

14. Workspace-Specific Config Templates (useWorker)

"fileheader.configObj": {
  "useWorker": false // Disabled by default
}

Allows differentiating between workspace-specific templates and user-level templates. When enabled, workspace and user settings are not merged for customMade and cursorMode.

15. Automatic Parameter Extraction for Function Comments

"fileheader.configObj": {
  "openFunctionParamsCheck": true // Enabled by default
}

When enabled, the plugin automatically extracts parameters from the function signature and includes them in the function comment. Supported languages include JavaScript, TypeScript, Python, Java, Go, Rust, C/C++, PHP, and Solidity.

Custom Language Support

To enable parameter extraction for custom languages defined in language:

"fileheader.configObj": {
  "language": {
    "tsx": {
      "head": "/**",
      "middle": " * ",
      "end": "*/",
      "functionParams": "typescript" // Use TypeScript parsing logic
    }
  }
}

Use the language keys from the plugin's internal mapping: javascript, typescript, java, python, rust, go, c, cpp, php, solidity.

16. Generating Function Comments Inside Function Body

"fileheader.configObj": {
  "cursorModeInternalAll": {
    "ts": true,   // Inside function for .ts files
    "js": false,  // Outside function for .js files
    "python": true, // Inside function for Python
    "defaultSetting": false // Default: outside function
  }
}

17. Function Comment Blank Line Indantation

"fileheader.configObj": {
  "functionBlankSpaceAll": {
    "js": 2,
    "python": 4,
    "defaultSetting": 0
  }
}

18. Customizing Function Parameter Format (functionParamsShape)

"fileheader.configObj": {
  "functionParamsShape": ["{", "}"], // Default: wrap type in {}
  // "functionParamsShape": "no type" // Remove type from params
}

19. Default Symbol for Untyped Parameters (functionTypeSymbol)

"fileheader.configObj": {
  "functionTypeSymbol": "*" // Default: use * for untyped params
}

20. Parameter Type/Value Order (typeParamOrder)

"fileheader.configObj": {
  "typeParamOrder": "type param" // Default: type before param
  // "typeParamOrder": "param type" // Example: param before type
}

21. Customizing Comment Head/End Removal (customHasHeadEnd)

Valid only when language is also configured.

"fileheader.configObj": {
  "customHasHeadEnd": {
    "js": "cancel head and function", // Remove head and end for both header and function comments
    "ts": "cancel function",          // Remove head/end only from function comments
    "python": "cancel head"           // Remove head/end only from header comments
  }
}

22. Throttling Comment Updates (throttleTime)

Reduces the frequency of comment updates to avoid issues when reverting changes.

"fileheader.configObj": {
  "throttleTime": 60000 // 60000 ms (1 minute) between updates for the same file
}

The plugin tracks the last 30 files using an LRU algorithm.

---

This documentation is adapted from the koroFileHeader Wiki: https://github.com/OBKoro1/koro1FileHeader/wiki/%E9%85%8D%E7%BD%AE