Tips & Tricks

DoxyIT - Script for insert Doxygen headers

A Python Script for Notepad++ Python Script (v.2) that provides you with the abillity to insert:

File header
Function header
Delimiter pre-filled with file name, function name, parameters, author name and email, date stamps

Changing:

to:

(Red=File header, purple=Function header, orange=Delimiter)

It’s inspired by dail8859’s DoxyIt @@Doxyit_logo@@ which had the simple ablillity to insert file and function headers by hotkey formatted by file extention.

“This also provides helpful features for creating and editing comment blocks, even if Doxygen isn’t desired.”

The setup has the following elements:

File	Function
`src/doxyit.py`	The script it self
`src/doxyit.json`	Configuration
`src/doxyit_lib.py`	A function library for the script

Test files:

File	Function
`test/test.cmd`	DOS batch
`test/test.php`	PHP
`test/test.py`	Python

A Word of Advice

⚠️ WARNING

This IS my first Python 2 script and I’m not familiar with Python scripting.

I did NOT read the documentation (who does??!) but build this script entirely out of my head and using intense searches on the web. So suggestions are wellcome!

Many thanks to Stackoverflow @@Stackoverflow_icon@@

Installing DoxyIT

Install Notepad++ and fire up ;-)
Install Python Script for NotePad++
Download the scripts and configuration JSON - and place them in the script directory
Restart NotePad++
Add a hotkey for DoxyIt.

And you’re good to go.

Details of installations

Install Notepad++

Select a package from Notepad++ Downloads
Install the package
And fire up ;-)

🚨 CAUTION

IF you’re dazed and confused at this point - don’t go any further!

Install Python Script for NotePad++

In Notpad++ select in menu:

Plugins / Plugins Admin...
Search for “PythonScript” and you’ll find:

Python Script plugin.

Author: Dave Brotherstone + Jocelyn Legault

Homepage: https://github.com/bruderstein/PythonScript
Select the pachage and press Install
Answer Yes to the question on restarting Notepad++
Notepad Plugin Admin will now download and install the plugin.

Ready to Rock’n’Roll!

Download the script and configuration

Run as Admin!

Select in menu:
1. Plugins / Python Script / Show console (You’ll like this for debugging)
2. Plugins / Python Script / New script - to create your first script
Go to https://clicketyclick.github.io/TipsAndTricks/Notepad++/Doxyit/
1. Copy the content of src/doxyit.json

Download the scripts and configuration JSON and place them in the script directory: "%APPDATA%\Notepad++\plugins\Config\PythonScript\scripts\doxyit.py"

Go to Plugins / Python Script / Configuration
The script doxyit.py will be visible in the top window
Select the script and press Add at the left window named “Menu Items”
Finish by pressing OK
Restart NotePad++

The script Doxyit now appears directly in the Python Script menu (Plugins / Python Script)

Add a hotkey for DoxyIt.

In general: How do I run specific script with a keyboard shortcut? / Scott Sumner

Go to Plugins (menu) -> Python Script -> Configuration. The Python Script Shortcut Configuration window will appear.

In the Scripts area at the top of the Python Script Shortcut Configuration window, locate and select the script you want to bind to a shortcut (and/or toolbar button).

Between the Scripts box and the Menu items (or Toolbar icons) caption there is an Add button. To get your script added as a menu item (necessary to bind a keycombo to it via the “Shortcut Mapper”), press the Add button (the one above the Menu items caption). Very similar but hopefully obvious what to do for a toolbar button.

Once you click OK to dismiss the Python Script Shortcut Configuration window, you should be able to go into Plugins (menu) -> Python Script (just point to that and let the menu cascade open) and then see your script at this level of the menu (between the Scripts-> and Configuration entries). Seeing your script appear here is key to being able to tie it to a shortcut keycombo.

Restart Notepad++. This allows the “Shortcut Mapper” to see that you’ve changed the Plugins (menu) -> Python Script menu contents.

Now go to Settings (menu) -> Shortcut Mapper… and select the Plugin commands tab. Scrolling down somewhat you should see your script in the Name column (along with “Pythonscript” in the Plugin column). Go ahead and select your script and assign a keycombo to it just like you would for any other command.

In “Filter”: type “doxyit” and the matching entries will be presented
Select “doxyit” and press Modify
Personally I select ⇧ Shift⌃ ControlD
Make sure that there are no conflicting sequenses

Using DoxyIT

Open a new file in NotePad++ and save it with the prefix, that tell DoxyIT which format to use:

Extension	Type
`.c`	C
`.php`	PHP
`.cmd`	Win/DOS Batch
`.py`	Python

Place the curser at the top of the file and press the hotkey. A file header is inserted.
Start your happy scripting - and when you create a subfunction
Place the cursor at the end of the line ABOVE the function definition - and press the hotkey again and a function header template is inserted.
As code pile up you can insert a separator line anywhere in you code (Except from the line above a function definition - and the first 5 lines of the script). Pres the hotkey and a separator line is inserted.

Or in more detail

A php script could look like this:

<?php

function test( $one, $two ){
	
}

Place the cursor at the top of the file and press the hotkey:

<?php
/**
 *   @file       test.php
 *   @brief      $(Brief description)
 *   @details    $(More details)
 *   
 *   @copyright  http://www.gnu.org/licenses/lgpl.txt LGPL version 3
 *   @author     Erik Bachmann <Erik@ClicketyClick.dk>
 *   @since      2024-09-26T15:23:32 / erba
 *   @version    2024-09-26T15:23:32
 */
//<?php

function test( $one, $two ){
	
}

A file header is inserted at the top of the file.

Note

The original <?php is now trailing the header.

You may now update the header (especially the tokens $(Brief description) and $(More details)

Move your cursor to the line just above the function test.

Press hotkey again:

//<?php

/**
 *   @fn         test
 *   @brief      $(Brief description)
 *   
 *   @param [in]	$one	$(description)
 *   @param [in]	$two	$(description)
 *   @return     $(Return description)
 *   
 *   @details    $(More details)
 *   
 *   @example    
 *   
 *   @todo       
 *   @bug        
 *   @warning    
 *   
 *   @see        https://
 *   @since      2024-09-26T15:25:08
 */

function test( $one, $two ){

And a function header for test() is inserted with parameters.

You may want to update the header ( $(description), $(Return description) and $(More details))

Move your cursor to the end of file and pres hotkey again:

function test( $one, $two ){
	
}
//----------------------------------------------------------------------

And a delimiter line is inserted.

Configuration

The entire configuration is stored in doxyit.json.

You can modify the templates to your own purposes - and add new file extensions.

	"title": "Data for Doxyit formatting",
	"date": "2024-09-24T18:17:43",
	"author": "Erik Bachmann <Erik@ClicketyClick.dk>",

Header description

	"templates": {
		"file": "${START}\n${LINE} ${PREFIX}....\n",
		"delimiter": "${START}-----------------....\n",
		"function": "${START}\n${LINE} ${PREFIX}fn         ${FUNCTION}\n.....\n${END}"
	},

The three templates used for building file header, function header and delimiter.

	"users": {
:
		"Bruger": {
			"name": "Bruger",
			"fullname": "User Name",
			"email": "SomeOne@ClicketyClick.dk",
			"phone": "+45",
			"address": "Thierd Stone from the Sun"
		}
	},

Expanded user information. You can add your personal setup by duplicating one of the existing user blocks and insert your own data.

	"types": {
:
		"php": {
			"name": "PHP",
			"function": "function",
			"start": "/**",
			"line": " *  ",
			"prefix": "@",
			"param_outer": "${LINE} ${PREFIX}param [in]\t%s\t$(description)",
			"param_inner": "\t$(description)\n${LINE} ${PREFIX}param [in]\t",
			"end": " */"
		},

Extension specific data:

Key	Descripion
name	Descriptive name = programming language
function	Patterne used for identifying function definition
start	Start comment
line	New line START
end	End comment
delimiter	Delimiter line
header_zone	The zone at the top of file where file header is located (Defaule: 0-5)
prefix	Prefix for Doxygen terms
param_outer	Outer parameter¹
param_inner	Inner parameter¹

¹: param_outer is the basic line and param_inner is the delimiter inserted between multiple values

The parameter block is build by inserting the argument to the function as entries in the function header:

*   @param [in]	$abc	$(description)
*   @param [in]	$defg	$(description)
*   @return     $(Return description)

Given:

function f( X, Y )

the arguments X and Y separated by param_inner are inserted into param_outer

${LINE} ${PREFIX}param [in]\t%s\t$(description)
     ┌───────────────────────┘└────────────────────────┐ 
      X\t$(description)\n${LINE} ${PREFIX}param [in]\tY

and inserting in the function template at ${PARAM}

Tips & Tricks var REPO="TipsAndTricks";var DESC="Tips & Tricks";