v icon indicating copy to clipboard operation
v copied to clipboard

vdoc: Important info is left out of docs

Open JalonSolov opened this issue 1 year ago • 0 comments

Describe the bug

v doc output does not include attributes which affect how some things are used. For example @[flag] and @[params] attributes for structs.

Reproduction Steps

Look at code in vlib/builtin/array.v for ArrayFlags struct:

@[flag]
pub enum ArrayFlags {
	noslices // when <<, `.noslices` will free the old data block immediately (you have to be sure, that there are *no slices* to that specific array). TODO: integrate with reference counting/compiler support for the static cases.
	noshrink // when `.noslices` and `.noshrink` are *both set*, .delete(x) will NOT allocate new memory and free the old. It will just move the elements in place, and adjust .len.
	nogrow // the array will never be allowed to grow past `.cap`. set `.nogrow` and `.noshrink` for a truly fixed heap array
	nofree // `.data` will never be freed
}

Compare that to the https://modules.vlang.io/index.html#ArrayFlags info. It is not mentioned anywhere that ArrayFlags is a flag enum, rather than a plain enum.

Expected Behavior

See indication of the @[flag] attribute.

Current Behavior

No indication.

Possible Solution

Have v doc tag the struct in some fashion, perhaps the same way it tags unsafe functions.

Additional Information/Context

No response

V version

V 0.4.4 07016fb

Environment details (OS name and version, etc.)

Doesn't matter.

[!NOTE] You can use the 👍 reaction to increase the issue's priority for developers.

Please note that only the 👍 reaction to the issue itself counts as a vote. Other reactions and those to comments will not be taken into account.

JalonSolov avatar Feb 02 '24 16:02 JalonSolov