vshaxe / codedox

Extension for Visual Studio Code that helps Haxe developers document their code.

Codedox for Haxe and Visual Studio Code

This is an extension for Visual Studio Code that helps developers document their Haxe code.

JSDoc style comments can be inserted including automatic generation of @param and @return tags. File headers can be inserted with customizable copyright and license comments, or you can choose from a variety of built-in license texts.

This extension is best used as a companion to vshaxe which provides Haxe support for Visual Studio Code.

Usage

1. Type /* at top of file to insert a file header.
   • if no file header template has been configured then a simple setup wizard will ask a few questions and save the configuration
2. Position cursor before a function declaration and type /** to insert a JSDoc-style comment.
3. Position cursor before a variable or class declaration and type /** to get an empty JSDoc-style comment, then press enter immediately to get a multiline comment.

File header and JSDoc-style comments can also be inserted using commands. Invoke the commands using F1 or Ctrl-Shift-P/Cmd-Shift-P and typing Codedox: Insert ...

Features

Insert JSDoc comment

On-enter rules

Insert file header

Setup 'Wizard'

A basic configuration can be created using the simple setup 'wizard'. This is triggered when typing /* at the top of a file for the first time, or by running the setup command using F1 or Ctrl-Shift-P/Cmd-Shift-P and typing Codedox: Setup ....

The wizard will ask:

1. Where you want the configuration saved (user or workspace)
2. Which of the built-in license templates you want to use (if any)
   • GNU Affero General Public License
   • Apache License, Version 2.0
   • GNU General Public License, Version 3.0
   • MIT License
   • Mozilla Public License, Version 2.0
   • Simple copyright
3. A company/author name to include in your copyright.

Advanced Configuration

Most Codedox settings are optional, and all required settings can be generated by the setup wizard. If you want use a built-in license template or simple copyright then just run the setup wizard and skip this section.

If you want to create a custom license/copyright template or want to change how the comments look, then you can cut and paste the following into your user or workspace settings file (.vscode/settings.json) and customize as needed. A list of built-in parameters that can be used in your custom templates is also listed below.

{
  "codedox": {
    "autoInsert": true, // enables insertion of function comments trigged by keystrokes
    "autoInsertHeader": true, // enables insertion of file header triggered by keystrokes
    "autoPrefixOnEnter": true, // enables 'on enter' rules
	"paramFormat": "@param ${name} ",  // supports ${name} and ${type}, plus built-in params
	"returnFormat": "@return ${type}", // supports ${type}, plus built-in params
	"allowOptionalArgs": false, // false strips the '?' prefix from optional function args
	"alwaysMultiline": true, // if false non-functions (types) are single line
    "commentprefix": " * ",
    "commentbegin": "/**",
    "commentend": " */",
    "commentdescription": "[Description]",
    "headerprefix": "*",
    "headerbegin": "/*",
    "headerend": " */",
    "fileheader": {
      "params": {
        "*": {
          "company": "My Company",
          "author": "Wiggin"
        }
      },
      "templates": {
        "*": [
          "${headerbegin}",
          "${headerprefix} Copyright (c) ${year} ${company}",
          "${headerprefix}",
          "${headerprefix} Author: ${author}",
          "${headerend}"
        ]
      }
    }
  }
}

Built-in parameters:

Param	Result
${name}	variable name (function comments only)
${type}	variable or function type (function comments only)
${fname}	name of current file
${fspec}	absolute path and name of current file
${frel}	path and name of current file relative to workspace
${year}	2017
${month}	1
${day}	2
${timestamp}	2017-01-02 15:17:40
${time24h}	15:17:40
${date}	2017-01-02
${time}	3:17:40 PM
${license_agpl_3_0}	GNU Affero General Public License
${license_apache_2_0}	Apache License, Version 2.0
${license_gpl_3_0}	GNU General Public License, Version 3.0
${license_mit}	MIT License
${license_mozillapl_2_0}	Mozilla Public License, Version 2.0
${license_none}	Simple copyright

Notes

• If you do not want an asterisk preceding each line of a comment, replace the commentprefix property with two spaces (" ").
• If you prefer only one space before each line of a comment, replace commentprefix with asterisk plus one space ("* ").
• Feature requests, comments, etc, are welcome.

codedox's Issues

Enable Travis CI

.travis.yml added. @nadako could you turn this on at travis-ci.org when you get a moment?

Is it possible to use this for other syntaxes?

I use JSDOC style comments in my CSS and Sass and would really like some of the features from this package to be available in those syntaxes. Would it be very hard to allow for these other syntaxes?

P.S. I realise that some of the more complex features might not be available for these new syntaxes.

Was causing lag issues

Type: Bug

It was allowing me to still delete text but it would take forever to type out what I typed.

Extension version: 1.3.3
VS Code version: Code 1.77.0 (7f329fe6c66b0f86ae1574c2911b681ad5a45d63, 2023-03-29T10:02:16.981Z)
OS version: Windows_NT x64 10.0.19045
Modes:
Sandboxed: Yes

System Info

Item	Value
CPUs	AMD Ryzen 5 5600G with Radeon Graphics (12 x 3893)
GPU Status	2d_canvas: enabled canvas_oop_rasterization: disabled_off direct_rendering_display_compositor: disabled_off_ok gpu_compositing: enabled multiple_raster_threads: enabled_on opengl: enabled_on rasterization: enabled raw_draw: disabled_off_ok skia_renderer: enabled_on video_decode: enabled video_encode: enabled vulkan: disabled_off webgl: enabled webgl2: enabled webgpu: disabled_off
Load (avg)	undefined
Memory (System)	31.29GB (19.13GB free)
Process Argv	C:\Users\okmil\Pictures\Internet Downloaded\Friday Night Funkin'\Modding Stuff\Source Code\FNF-Imaginative-Engine --crash-reporter-id 6ebc8497-3402-4601-9d98-51c761580449
Screen Reader	no
VM	0%

A/B Experiments

vsliv368:30146709
vsreu685:30147344
python383:30185418
vspor879:30202332
vspor708:30202333
vspor363:30204092
vslsvsres303:30308271
vserr242cf:30382550
pythontb:30283811
vsjup518:30340749
pythonptprofiler:30281270
vshan820:30294714
vstes263:30335439
pythondataviewer:30285071
vscod805cf:30301675
binariesv615:30325510
bridge0708:30335490
bridge0723:30353136
cmake_vspar411:30581797
vsaa593:30376534
pythonvs932:30410667
cppdebug:30492333
vsclangdc:30486549
c4g48928:30535728
dsvsc012cf:30540253
pynewext54:30695312
azure-dev_surveyone:30548225
nodejswelcome1:30587005
282f8724:30602487
pyind779:30671433
f6dab269:30613381
pythonsymbol12:30671437
6233i204:30672705
vsctsb:30677850
pythonb192:30669360
azdwalk:30687957
pythonms35:30701012

No selection with \n in commentdescription

I wanted to see if I could use the "commentdescription" setting to add an empty line between the description and the following @param / @return. This works fine - however, with this config, [Description] does not get selected anymore:

"codedox": {
    "commentdescription": "[Description]\n"
}

Also, "commentprefix" is not included here - it probably should be?

Populating incorrect signatures.

I think it has trouble with generics x:A<Int> and nested generics like `x:A<B>, because when it encounters these cases, it populates the last signature in the current class rather than the current method. Interestingly, if the last signature happens to be a nested generic, it gets the signature right.

Extension needs to run once before picking up key commands

I find that i first need to run

Ctrl-Alt-P > Codedox: Insert comment at cursor

Before any key combinations are observed in the extension. Having run this once, key commands are then picked up successfully, even for newly opened files. Am I missing something?

${type} is inserted as-is without type hints

Settings:

"codedox": {
    "paramFormat": "@param ${type} - "
}

Due to type inference, it's not uncommon to leave out type hints for parameters. However, it looks ${type} is not replaced at all in that case:

It might be preferable to replace it with an empty string in cases like this?

Spaces added for non-function docs

The use case described in #10 now works well for functions. 👍

However, it looks like there's still an issue with docs elsewhere (for instance type or variable declarations). These are not "auto-expanded" to multiple lines like function docs, which is ok - however, it seems two spaces are inserted for these, which means when pressing enter, you have an additional space in front of the **/ again.

I played around with a few of the settings (autoInsert etc) but they didn't seem to make a difference.

Here are the settings the gif was recorded with:

"codedox": {
    "commentbegin": "/**",
    "commentprefix": "    ",
    "commentend": "**/",
    "headerbegin": "/**",
    "headerprefix": "    ",
    "headerend": "**/"
}

Btw, it looks like the "header" settings are used for type and variable declarations (not a problem per se, but might be confusing to some).

Definable @param format

I was wondering if it's currently possible to define the @param format?

Within Commenter.hx#L186 the construction of param comments could provide the current item's information as parameters; these could then be used in conjunction with a user-definable @param format, e.g.

{
    "codedox": {
        "paramformat": "@param {{${type}}} ${name}"
    }
   ...
}

Then for a given parameter name: string, the result would be @param {string} name

"commentend" has a hardcoded space?

I'm trying to configure codedox to generate comments with the style with which they're commently used in the Haxe standard library (and also vshaxe).

They look like this:

/**
	Description
**/

To achieve this, I added this setting: "commentend": "**/"

However, it looks like there's no way to avoid an extra space in front of **/ from being generated:

Don't include '?' in @param tag for optional args

Apparently FlashDevelop and VSCode/Typescript don't include the '?' during comment generation for optional args. We should do the same.

See vshaxe/vshaxe#78 (comment)

Debug output visible in releases

This code is hidden behind #if debug, which suggests to me it's not supposed to show up in marketplace releases. However, it looks like marketplace releases are debug builds, as build.hxml has -debug and package.json has haxe build.hxml as its prebublish command.

${type} breaks with inline structure declarations

By default, codedox puts the returned type after @return:

However, when returning a structure, the return is missing:

class Main {
	public static function main() {}

	public function foo():{x:Int, y:Int} {
		return {x:0, y:0};
	}
}

The situation with @param is similar, once you configure codedox to use $type{} there:

class Main {
	public static function main() {}
	
	public function foo(point:{x:Int, y:Int}) {
		trace(point);
	}
}

onEnter rules with empty prefix break auto-indent

Settings:

{
    "codedox": {
        "commentbegin": "/**",
        "commentprefix": "  ",
        "commentend": "**/",
    }
}

With "autoPrefixOnEnter": false, it works normally:

`

I don't think on enter rules are really needed to begin with with an empty commentprefix, that "just works" due to VSCode's handling (keeps the indent level the same on enter). Perhaps they should just not be registered in that case?

Incorrect doc template created when function takes a function as a parameter

Haxe 4.3.3
VScode Haxe Language Support extension v2.31.0
codedox v1.3.3.

For example if I have this function defnition

	public function foo(completionCbk:(result:LoaderResult) -> Void = null):Void {}

and then type /** above it I get this:

	/**
	 * [Description]
	 * @param completionCbk 
	 * @return -> Void = null):Void
	 */
	public function foo(completionCbk:(result:LoaderResult) -> Void = null):Void {}

Indent detection

Generated doc comments always seem to use tabs for indentation, even if the rest of the file uses spaces:

File name and base file name Parameters

Is it possible to add a filename and baseFileName to the existing parameters.

Publish extension to open-vsx.org

Please submit the extension to the Open VSX registry/marketplace.

This way it can be legally downloaded/installed in opensource builds/forks of VSCode, e.g. VSCodium and Eclipse Theia.

FAQs: https://www.eclipse.org/legal/open-vsx-registry-faq/

Thanks!

Haxe comment conventions for dox

Shouldn't this extension adhere to Haxe dox-style comment conventions?

By default, it implements a JSDoc / ASDoc style comments:

When this style of comment is run through dox, the resulting documentation does not parse method parameters correctly:

    /**
     *  Constructor
     *  @param delay - The delay in ms to make the call.
     *  @param scope - An object that specifies the scope (value of `this` object) within the function body.
     *  @param callback - Function to call after the specified delay.
     *  @param params - Parameters to be passed to the function.
     */
    public function new(delay:Int = 1, ?scope:Dynamic, ?callback:Dynamic, ?params:Array<Dynamic>) {

Instead, a configuration must be added:

    "codedox": {
        "commentbegin": "/**",
        "commentprefix": "    ",
        "commentend": "**/",

These conventions are correctly interpreted to produce dox documentation

    /**
        Constructor
        @param delay     The delay in ms to make the call.
        @param scope     An object that specifies the scope (value of `this` object) within the function body.
        @param callback  Function to call after the specified delay.
        @param params    Parameters to be passed to the function.
    **/
    public function new(delay:Int = 1, ?scope:Dynamic, ?callback:Dynamic, ?params:Array<Dynamic>) {

Why are these conventions not implemented by default?

Header-Width

Thank you for this very useful Plugin.
Can you please add a width property within the settings, to which the total length of a line will be stretched? As example for powershell, my favorite header looks as follows:

###############################################
#                                             #
#   FILENAME.....: Testfile.ps1               #
#   AUTHOR.......: MyUser                     #
#   COMPANY......: MyCompany                  #
#   DATE.........: 2018-04-07                 #
#   VERSION......: 1.0                        #
#   DESCRIPTION..:                            #
#   USAGE........:                            #
#                                             #
###############################################

Since I use variables, I have to manually adjust the line ends to get a comment block.

Suggest including License name at the top of default license template.

For example, it works as below in default now,

/*
 * Copyright (c) 2018 Yi-Soo An
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
 * Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:

Instead of that, I suggest including license name too as below,

/*
 * MIT License
 *
 * Copyright (c) 2018 Yi-Soo An
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
 * Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:

The second is more specific that which license it is based.

Thank you for developing this cool plugin!

Function body of braceless function used as return type

(default codedox settings)

In Haxe, it's perfectly acceptable to have function declarations without braces. In these cases, codedox seems to think the function body is the return type:

class Test {
	public static function main() {}

	static function noBraces(i:Int) return switch(i) {
		case 0: "0";
		case 1: "1";
		case _: "something else";
	}
}

Support for function expressions

I'm not sure if this a bug or an enhancement. I'm trying to generate some docs on the following function and docs are not generated.

lib.read = (dir, file, callback) => {
  fs.readFile(`${path.join(lib.rootDir, dir, file)}.json`, 'utf-8', (err, data) => {
      callback(err, data)
    }
  )
}

My guess is that the extension just work with function declaration.

is @return only auto insert for ts files?

thank you! such a great plugin help me a lot! but I want to make out the @return section, it doesn't auto insert for my js file(also test with ts file). is that an expected feature, or maybe something go wrong?