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?

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.

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);
	}
}

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?

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

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)

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

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

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?

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.

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 {}

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.

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

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

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:

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!

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?

(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";
	}
}

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?

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?

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

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!

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.

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.

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).