Error with identically named method and property about gendocs HOT 4 CLOSED

The same problem occurs, when you try to document a setter snd getter for a property (which should have the same name):

/*! 
    Property: test [get]
        blaah
*/
...
/*! 
    Property: test [set]
        blaah
*/

from gendocs.

Not a bug, methods and properties with the same name are not supported as it is bad practice (why should obj.Test behave differently to obj.Test()?), unless I am missing something. Also, properties that can be both retrieved and set use [get/set], like so: (example taken from AFC)

/*!
    Property: Text [get/set]
        Represents the text of the control. Equivalent to `GuiControl(Get)`'s `Text` sub-command.
*/

from gendocs.

Partly agree - partly playing the devils's advocat on the other hand:

• Unless it's a bad practice, why shouldn't it be supported? GenDocs tries to supply support generating documentation on AHK-code. As AHK as a language allows this bad practice - why should GenDocs try to "educate" people, if the language itself allows it?
  Partly agree - on the other hand playing the devils's advocat:
• Unless it's a bad practice, why shouldn't it be supported? GenDocs tries to supply support generating documentation on AHK-code. As AHK as a language allows this bad practice - why should GenDocs try to "educate" people, if the language itself allows it?

why should obj.Test behave differently to obj.Test()?

• I've implemented a property obj.Test which can only be get by a getter - setting the object is done by a function with the same name. (Not quite sure, whether this makes sense - but it's possible with AHK ..)
  Another possibilty might be kind of 'overloading" the setter: whilst the setter property allows only one parameter to be set, with the function a kind of "extended setter" (having multiple arguments) is possible ...

Also, properties that can be both retrieved and set use [get/set]

• I personally do not like this method of centralizing documentation for two different things on a single place, as it does not allow to document things in place of implementation (For example: set is implemented in method __Setter(), get within __Getter() . As some of my properties do have set AND get, whilst other do have only get, I do have to recall during documentation: does this property have both set and get - or was there only get? Scrolling to metohd ... going back to documentation ... having forgotten some details ... scrolling again ... I hate centralized documentation of sourcecode! ;-))

Just a few thoughts ...

from gendocs.

Unless it's a bad practice, why shouldn't it be supported? GenDocs tries to supply support generating documentation on AHK-code. As AHK as a language allows this bad practice - why should GenDocs try to "educate" people, if the language itself allows it?

In my opinion, GenDocs should not support corner cases that do not occur in well designed libraries. Let me put it through an example: it is in theory possible in AHK to create subroutines that accept parameters through global variables, as a kind of bad substitute for functions. So basically your reasoning would be to have GenDocs support that as well, which makes no sense.

I've implemented a property obj.Test which can only be get by a getter - setting the object is done by a function with the same name. (Not quite sure, whether this makes sense - but it's possible with AHK ..) Another possibilty might be kind of 'overloading" the setter: whilst the setter property allows only one parameter to be set, with the function a kind of "extended setter" (having multiple arguments) is possible ...

You should rename the "setter" to something like obj.SetTest() or even obj.ConfigureTest(), since it takes multiple parameters and is thus not a setter (there is the thumb rule that obj.Property := obj.Property should be supported and valid).

The "extended setter" possibility is just the same: you have a normal get/set property but you have an additional method which allows for configuring more options.

I personally do not like this method of centralizing documentation for two different things on a single place, as it does not allow to document things in place of implementation

Please think of this from the point of view of GenDocs: you get two property blocks referring to the same property, but with different attributes (different parameters, remarks, extra information...). How is GenDocs supposed to know how to merge them? Describing both getter and setter functionality in a single property block allows for a better overall explanation of what the property is, as opposed to an implementation-centric split description between the getter and the setter. What do you think is better: "Retrieves the name / Sets the name" or "Represents the name"?

Also, AutoHotkey's property system is different in the sense that languages normally provide a construct to define both the setter and the getter for each property in the same block, whereas AutoHotkey separates the getters from the setters in two different groups. If all, it is not GenDocs' fault for forcing you to group setters in one big block and getters in another.

from gendocs.