Re: Methods, Components, Comments, and Tooltips

[John DeSoi via 4D_Tech]

> On Apr 21, 2017, at 9:59 AM, Chip Scheide <4d_o...@pghrepository.org> wrote:
> 
> What does this project method look like?
> 
> Case of
> :(form event=)
>  case of
>   :(Last object = )
> do stuff


Example below. All calls to Form event in the database are replaced with a 
wrapper FM_Form_event. Same for current object/focus object commands.

So execution of an object method sets up the form context and then executes 
this method with the object name. No need to make every object method call a 
project method or maintain the code below -- it is automatically generated from 
the form.



John DeSoi, Ph.D.





  // Auto generated by DVT_Generate_form_test_method.

  //$1 - Form object name.

C_TEXT($1)

Case of 
: ($1="Field16")
  LINK1_Table (->[Company];FM_Object_self ;->[Label]Company_ID)

: ($1="Button4")
  ESCROW_UPDATE (->[Label]Escrow_Min_Threshold;True)

: ($1="BUTTON3")
  UI_OPEN_URL ([Label]URL)

: ($1="Invisible Button4")
  UI_Table_input_view (->[Company];[Label]Company_ID)

: ($1="BUTTON2")
  UI_OPEN_URL ([Label]Email;"")
End case 

DV_FORM_EVENT 
**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[Chip Scheide via 4D_Tech]

What does this project method look like?

Case of
:(form event=)
  case of
   :(Last object = )
 do stuff




On Fri, 21 Apr 2017 07:49:11 -0500, John DeSoi via 4D_Tech wrote:
> I recently embarked on an automated testing project and implemented 
> the advantages you mention by automatically generating *one* project 
> method per form that contains all of the object method and form 
> method code. The only other task was to create wrappers for Form 
> event and OBJECT Get pointer to allow them to be programmatically 
> manipulated.
> 
> So no rewriting of the form is necessary, no need to call a project 
> method from every object method, and no need to maintain an enormous 
> case statement for a form with lots of object methods. The "form 
> controller" idea others have mentioned might be nice for newer 
> projects, but would be a huge amount of work for legacy projects 
> where object names did not exist. My generated code has lots of 
> "Field1", "Field2", "Button1" names because object names never 
> mattered when the forms were created.
> 
> John DeSoi, Ph.D.
> 
> 
>> On Apr 20, 2017, at 4:34 PM, David Adams via 4D_Tech 
>> <4d_tech@lists.4d.com> wrote:
>> 
>> Using a project method in place of a a form method/object scripts has a
>> couple of other advantages. If you pass in the event code, then you can:
>> 
>> * Create custom event codes ('redraw', 'close' or something more like a
>> message)
>> 
>> * Emulate form activity (useful for testing)
>> 
>> * Leverage your existing code with CALL FORM. Your CALL FORM call invokes
>> the form handler method and passes in whatever event or data is required.
> 
> **
> 4D Internet Users Group (4D iNUG)
> FAQ:  http://lists.4d.com/faqnug.html
> Archive:  http://lists.4d.com/archives.html
> Options: http://lists.4d.com/mailman/options/4d_tech
> Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
> **
---
Gas is for washing parts
Alcohol is for drinkin'
Nitromethane is for racing 
**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[Chip Scheide via 4D_Tech]

I have asked for - repeatedly - 
4D to give us an automated means to "fix" this.
http://forums.4d.fr/Post/EN/8282868/1/8282870#8282870
(15 votes from 2012)

Basically - a means to change unchanged object names (variable1, Field3 
etc) to AT LEAST the variable name,
but with an option to pre/post append a fixed string (Ex: "obj_"  --> 
obj_My_Variable) to be able to distinguish between veritable references 
and object references.
 
and from Bob Miller:
http://forums.4d.fr/Post/EN/13792407/1/13792408#13792408

On Fri, 21 Apr 2017 07:49:11 -0500, John DeSoi via 4D_Tech wrote:
> I recently embarked on an automated testing project and implemented 
> the advantages you mention by automatically generating *one* project 
> method per form that contains all of the object method and form 
> method code. The only other task was to create wrappers for Form 
> event and OBJECT Get pointer to allow them to be programmatically 
> manipulated.
> 
> So no rewriting of the form is necessary, no need to call a project 
> method from every object method, and no need to maintain an enormous 
> case statement for a form with lots of object methods. The "form 
> controller" idea others have mentioned might be nice for newer 
> projects, but would be a huge amount of work for legacy projects 
> where object names did not exist. My generated code has lots of 
> "Field1", "Field2", "Button1" names because object names never 
> mattered when the forms were created.
> 
> John DeSoi, Ph.D.
> 
> 
>> On Apr 20, 2017, at 4:34 PM, David Adams via 4D_Tech 
>> <4d_tech@lists.4d.com> wrote:
>> 
>> Using a project method in place of a a form method/object scripts has a
>> couple of other advantages. If you pass in the event code, then you can:
>> 
>> * Create custom event codes ('redraw', 'close' or something more like a
>> message)
>> 
>> * Emulate form activity (useful for testing)
>> 
>> * Leverage your existing code with CALL FORM. Your CALL FORM call invokes
>> the form handler method and passes in whatever event or data is required.
> 
> **
> 4D Internet Users Group (4D iNUG)
> FAQ:  http://lists.4d.com/faqnug.html
> Archive:  http://lists.4d.com/archives.html
> Options: http://lists.4d.com/mailman/options/4d_tech
> Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
> **
---
Gas is for washing parts
Alcohol is for drinkin'
Nitromethane is for racing 
**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[John DeSoi via 4D_Tech]

I recently embarked on an automated testing project and implemented the 
advantages you mention by automatically generating *one* project method per 
form that contains all of the object method and form method code. The only 
other task was to create wrappers for Form event and OBJECT Get pointer to 
allow them to be programmatically manipulated.

So no rewriting of the form is necessary, no need to call a project method from 
every object method, and no need to maintain an enormous case statement for a 
form with lots of object methods. The "form controller" idea others have 
mentioned might be nice for newer projects, but would be a huge amount of work 
for legacy projects where object names did not exist. My generated code has 
lots of "Field1", "Field2", "Button1" names because object names never mattered 
when the forms were created.

John DeSoi, Ph.D.


> On Apr 20, 2017, at 4:34 PM, David Adams via 4D_Tech <4d_tech@lists.4d.com> 
> wrote:
> 
> Using a project method in place of a a form method/object scripts has a
> couple of other advantages. If you pass in the event code, then you can:
> 
> * Create custom event codes ('redraw', 'close' or something more like a
> message)
> 
> * Emulate form activity (useful for testing)
> 
> * Leverage your existing code with CALL FORM. Your CALL FORM call invokes
> the form handler method and passes in whatever event or data is required.

**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

RE: Methods, Components, Comments, and Tooltips

[Epperlein, Lutz (agendo) via 4D_Tech]

Kirk,

Interesting approach. And your remark about deleted methods rings a bell ...

> Something this won't catch that Josh's VC did is deleted methods...

Yes, the vc-framework handles deleted methods for export. It means if I delete 
a method in 4D the former exported text file with the code is deleted too. But 
in our extended version with import this is an issue. There is no way in 4D to 
delete a method via programming I'm aware of. So we have to use intense 
communication, say I have to tell my colleagues there is an deleted method 
please delete it too. A check-out of the repository isn't enough.

**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[Nigel Greenlee via 4D_Tech]

Tom

I handle forms in my version control. I use a method to get all form objects 
into an object-its an object of my own format…here is a sample below. Pretty 
extensive. I have code to pack and unpack the form objects so i can compare 
current version of a form with the last one (not using diff) to tell me in 
plain english what is changed. The object is put into t blob and written out to 
a version control document

the object is build using a call like this...

CORE_T_ParseFormName:=$_aT_FormNames{$_L_Index}
FORM LOAD($_aT_FormNames{$_L_Index})
C_OBJECT($CORE_ob_FormObject)
CLEAR VARIABLE($CORE_ob_FormObject)
CORE_GetFormObjects ($_aT_FormNames{$_L_Index};0;->$CORE_ob_FormObject)

I have put a copy of CORE_GetFormObjects on my 
dropbox..https://www.dropbox.com/s/banb0mpgllkj8na/CORE_GetFormObjects.txt?dl=0 
its fairly self explanatory if a little wordy..its shockingly fast i mean 
really uncompiled ‘boom' all them form objects parsed into an object faster 
than a fast thing.

If I was modifying it i would not have the constants hard coded as i now have 
code I got from the forum for reading the names of all 4D constants.


Three caveats….

1) if you try to get the menu bar of the form i think you just get the current 
menu bar(i build my menus on the fly anyway so this is not an issue for 
me)..but it can lead to you being told the menu bar has changed!
2) If you use inherited forms when you parse a form you get the inherited form 
objects and you can have an object named the same on the inherited form as on 
the inheriting form(!) and when you get the form objects they don't always come 
in the same order, this can lead to an object x on the inherited form being 
found in the array of objects before the object on the inheriting form on pass 
and then next time after-which can lead to you reporting that the object type 
has changed-i just make sure my object names on inherited forms are unique!
3)There are a couple of properties you can't get-they are as follows:-
//the following form setting cannot be obtained in code
//Markers
//access
//menu bar
//print settings
//appearance
//form type
//inherited form table
//inherited form name
//save geometry
(This is on V14 maybe on 15/16 you can get these)


this(without much comment) is the code i use to report the differences between 
two form objects(current and previous) 
https://www.dropbox.com/s/9u16tzd9db6689i/Diff_CompareForms.txt?dl=0



{"Form Name":"CODE_CHANGES","Number of Pages":2,"Fixed Width":false,"Fixed 
Height":false,"Form Title":"","Form Menu":"","Active Form Events":["On 
Load","On Validate","On Clicked","On outside Call","On Double CLicked","On 
drop","On menu selected","on Plug in area","on data change","On drag over","On 
timer","On after keystroke","on after edit","On begin drag over","On bound 
variable change","On mac toolbar button","On page change"],"Form 
Objects":[{"Page Number":1,"Name":"oCODLBChangesVIewer","Variable 
Name":"CODE_abo_MethodChanges","Type":7,"Type Name":"Object type 
listbox","Multiline option":0,"Multiline option Name":"Multiline Auto","Style 
Sheet":"__automatic__","Font Name":".SF NS Text","Font Size":12,"Font 
Style":0,"Font Style Name":"Plain","Is visible?":true,"Foreground 
Colour":"Foreground Color","Background Colour":"Foreground Color","Alternate 
Background Colour":"Foreground Color","Left Position":144,"Top 
Position":55,"Right Position":495,"Bottom Position":604,"Horizontal 
Resize":0,"Horizontal Resize Name":"Resize horizontal None","Vertical 
Resize":0,"Vertical Resize Name":"Resize Vertical None","Horizontal 
Alignment":1,"Horizontal Alignment Name":"Align …lots more here-cutting this as 
its a long bit of text


I have recently added a ‘watcher’ process which looks for all forms modified 
since the last time it looked(it looks every few mins) and if a form is 
modified runs code to compare it and save a new version of the object out. 
Happy to hear from anyone with comment/critique on this code.


> On 20 Apr 2017, at 14:04, Benedict, Tom via 4D_Tech <4d_tech@lists.4d.com> 
> wrote:
> 
> Lutz writes:
> 
>> we use a modified version of the mentioned vc-framework component. It saves 
>> all changes in the code to text files
>> immediately and keeps track of the timestamps of the changes in an external 
>> database. The text files can be
>> committed to a source code versioning tool like svn, mercurial, git ...
> 
>> We extended it a bit to allow reimporting of the exported code. So we are 
>> able to switch between branches and
>> we can do team development without a development server and dev clients. All 
>> members of our team use single user >instances of 4D. The result of the 
>> development will be compiled into a built/merged server application.
>> A very old version (V13 yet) with import code can be found on Github: 
>> https://github.com/elutz/vc-framework-v13
> 
> Do your apps use 4D forms? If so, how do you deal with them with respect to 
> version control?
> 
> Thanks,
> 
> Tom Benedict

RE: Methods, Components, Comments, and Tooltips

[Epperlein, Lutz (agendo) via 4D_Tech]

> Do your apps use 4D forms? If so, how do you deal with them with respect to 
> version
> control?

No, our approach doesn't cover forms, it is usable only for methods like 
project methods, object methods, form methods, short: all methods editable in 
the method editor of 4D.
Since our application is a web app mainly, this isn't such a great problem, at 
least not for us.
**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

RE: Methods, Components, Comments, and Tooltips

[Benedict, Tom via 4D_Tech]

Lutz writes:

>we use a modified version of the mentioned vc-framework component. It saves 
>all changes in the code to text files
>immediately and keeps track of the timestamps of the changes in an external 
>database. The text files can be
>committed to a source code versioning tool like svn, mercurial, git ...

>We extended it a bit to allow reimporting of the exported code. So we are able 
>to switch between branches and
>we can do team development without a development server and dev clients. All 
>members of our team use single user >instances of 4D. The result of the 
>development will be compiled into a built/merged server application.
>A very old version (V13 yet) with import code can be found on Github: 
>https://github.com/elutz/vc-framework-v13

Do your apps use 4D forms? If so, how do you deal with them with respect to 
version control?

Thanks,

Tom Benedict
Optum

This e-mail, including attachments, may include confidential and/or
proprietary information, and may be used only by the person or entity
to which it is addressed. If the reader of this e-mail is not the intended
recipient or his or her authorized agent, the reader is hereby notified
that any dissemination, distribution or copying of this e-mail is
prohibited. If you have received this e-mail in error, please notify the
sender by replying to this message and delete this e-mail immediately.
**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

RE: Methods, Components, Comments, and Tooltips

[Epperlein, Lutz (agendo) via 4D_Tech]

Hi Nigel,

basically I'm interested, we are following a similar approach. I should explain 
it a bit.

At first we use a modified version of the mentioned vc-framework component. It 
saves all changes in the code to text files immediately and keeps track of the 
timestamps of the changes in an external database. The text files can be 
committed to a source code versioning tool like svn, mercurial, git ...
This is the basic idea behind the vc-framework. 

We extended it a bit to allow reimporting of the exported code. So we are able 
to switch between branches and we can do team development without a development 
server and dev clients. All members of our team use single user instances of 
4D. The result of the development will be compiled into a built/merged server 
application. 
A very old version (V13 yet) with import code can be found on Github: 
https://github.com/elutz/vc-framework-v13

But there are some disadvantages of this approach, all based on the limitations 
of 4D's way to handle the code. 
At first, the comparison of the exported and the present code in the database 
is based only on timestamps, that is a bit fragile. Most of the time it works, 
but if problems are happening the solution is sometimes difficult and a bit 
time consuming (re-export and re-import of thousands of methods). 
Another problem is the reliability of the component since 4D V15. Very often 
the immediate export of the code doesn't work and you have to trigger it 
manually. If the developer forget this additional step, he will check in only a 
part of his new code.
Because of that we don't recommend to take it 1:1 regardless we are using it a 
quite long time. 
As a task we have to invest time to improve and adapt the component to make it 
more reliable again.

I hope, there were some interesting thoughts ...

Regards
Lutz

**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[Wayne Stewart via 4D_Tech]

Actually there is

code analysis component free
Dani Beaubien

And

Archive Method(?)  commercial it's foundation App Store
Robert Livingston

You should be able to find them with those details.

I've used both but I prefer Code Analysis component. .

Cheers

Wayne


On Thu, 20 Apr 2017 at 20:37, David Adams via 4D_Tech <4d_tech@lists.4d.com>
wrote:

> >  how does one get access to the 4D source code outside of 4D?  Is there a
> magic command to get 4D
> >  to regurgitate its code into plain text?
>
> I was talking about the code in your database, which is accessible (read
> and write) using the commands described here:
>
> http://doc.4d.com/4Dv16/4D/16/Design-Object-Access.201-3035747.en.html
>
> > 2 - examples of “integrated code scanners” please
>
> A fair few people and teams in the 4D world have written such things, but
> there isn't a commercial example.
> **
> 4D Internet Users Group (4D iNUG)
> FAQ:  http://lists.4d.com/faqnug.html
> Archive:  http://lists.4d.com/archives.html
> Options: http://lists.4d.com/mailman/options/4d_tech
> Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
> **

-- 

Regards,

Wayne


[image: --]
Wayne Stewart
[image: http://]about.me/waynestewart

**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[David Adams via 4D_Tech]

>  how does one get access to the 4D source code outside of 4D?  Is there a
magic command to get 4D
>  to regurgitate its code into plain text?

I was talking about the code in your database, which is accessible (read
and write) using the commands described here:

http://doc.4d.com/4Dv16/4D/16/Design-Object-Access.201-3035747.en.html

> 2 - examples of “integrated code scanners” please

A fair few people and teams in the 4D world have written such things, but
there isn't a commercial example.
**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[Nigel Greenlee via 4D_Tech]

Luiz

I have a nice set of code that exports the code, including the forms(as 
objects),and all the database settings including table structure,  and 
maintains a history(in an external database) of everything using a modified 
DIFF . I would be happy to give you a copy of my component(including source) 
for doing this(i would need to change it a a bit  to work for you as it does a 
couple of other things-sets a header on the methods (and you might want that 
but you might want it different), and declares all my variables(you would not 
want that as I doubt it will comply with your naming convention). The code is 
set up for single user usage-so if you do client server development i would 
need to rethink some stuff on there-which i need to do anyway.


There are other people around with similar tools.

> On 20 Apr 2017, at 11:16, Epperlein, Lutz (agendo) via 4D_Tech 
> <4d_tech@lists.4d.com> wrote:
> 
>> 1 - how does one get access to the 4D source code outside of 4D?  Is there a 
>> magic
>> command to get 4D to regurgitate its code into plain text?
> 
> METHOD GET CODE
> Since V13
> Than you can do what you want with the text. An example is the VC-Framework 
> component by J. Fletcher: https://github.com/4D/vc-framework-v13
> 
> 
> Regards Lutz
> 
> **
> 4D Internet Users Group (4D iNUG)
> FAQ:  http://lists.4d.com/faqnug.html
> Archive:  http://lists.4d.com/archives.html
> Options: http://lists.4d.com/mailman/options/4d_tech
> Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
> **

**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

RE: Methods, Components, Comments, and Tooltips

[Epperlein, Lutz (agendo) via 4D_Tech]

> 1 - how does one get access to the 4D source code outside of 4D?  Is there a 
> magic
> command to get 4D to regurgitate its code into plain text?

METHOD GET CODE
Since V13
Than you can do what you want with the text. An example is the VC-Framework 
component by J. Fletcher: https://github.com/4D/vc-framework-v13


Regards Lutz

**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[David Eddy via 4D_Tech]

David -

On Apr 20, 2017, at 3:42 AM, David Adams wrote:

> From: David Adams >
> 
> Forgot to say specificallyyou can do a whole lot of Very Good Things
> with an integrated code scanner. Things that the 4D compiler does not do,
> and much more:


Two questions:

1 - how does one get access to the 4D source code outside of 4D?  Is there a 
magic command to get 4D to regurgitate its code into plain text?

2 - examples of “integrated code scanners” please

- David Eddy

**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[David Adams via 4D_Tech]

Forgot to say specificallyyou can do a whole lot of Very Good Things
with an integrated code scanner. Things that the 4D compiler does not do,
and much more:

* Check that method names passed as strings are valid.

* Check that parameter lists are not too long or too short.

* Confirm that variables, etc. match your team's naming conventions, etc.

* Locate code that violates your standards. For example, perhaps you have
abandoned Open window or want all calls to ALERT to call a custom routine
instead.

* Etc.

Some of the folks that have worked on big teams can probably chime in with
some of their real-world examples. Such validators are helpful in several
ways:

* You find bugs in the code at rest that otherwise only show up at runtime.
Like the bad method name or extra parameter examples above.

* You can help a new team member learn your rules very quickly. Instead of
just writing code and then getting a review (or not) from another worker,
the scanner spots deviations and you can bring the youngster into the fold
that much faster.

* It's a virtuous circle. As soon as you master one level of quality
improvement, there is another step you can take that's now within reach.
Distant horizons eventually turn into the road behind you.

It's absurd that 4D's compiler doesn't do more of this work for us and it
would be great if they would at least add in the easy ones:

Compiler/Typing Improvements: Detect some runtime errors in advance
http://forums.4d.fr/Post/EN/19107688/1/19107689

Please give this one a vote. At least then I get the satisfaction of
knowing that my ignored features requests are popular. This one seems to be
at the top of the charts, by a huge margin. Perhaps it needs some more
votes too:

Raise the 31 character name limit on methods
http://forums.4d.fr/Post/EN/18946884/1/18946885
**
4D Internet Users Group (4D iNUG)
FAQ:  http://lists.4d.com/faqnug.html
Archive:  http://lists.4d.com/archives.html
Options: http://lists.4d.com/mailman/options/4d_tech
Unsub:  mailto:4d_tech-unsubscr...@lists.4d.com
**

Re: Methods, Components, Comments, and Tooltips

[David Adams via 4D_Tech]

First up, thanks to Wayne for starting this thread and for being a Good
Citizen and providing code to match. Also thanks to Bruno for expanding the
context for talking about automatic documentation. As it turns out, this is
all related to one of my more recent proof-of-concept pieces. (For the past
couple of years, I've been doing a ton of experimental projects to get into
the details of various tools and design patterns.)

Anyway, to make an auto-doc feature, you need a code scanner. Grab the
comments, read the structured comments, extract the data and then do
something with it. For example:

* Produce HTML or PDF documentation.
* Set tooltips.
* Write the descriptions to a JSON file, XML file, text dump, or records.
* Generate test cases based on the declarations and comments.

As Bruno mentioned, there is a ton that can go wrong with documentation.
It's a pain to write, a pain to maintain, and a pain to validate. Moving
the comments into structured comments improves all of this (particularly
with macros), but it doesn't solve the problem completely. I'll be clear:
It's a very good solution, but it's not complete. So all respect to anyone
such as Bruno that's gone to the effort to implement and use such a
solution. We should all be so conscientious.

So what's the problem? The problem is that comments aren't code. Structured
comments are a kind of *promise* about what the code does and how it
behaves, but they are *unenforced* promises. So, there's another level to
what you can do with automated comments - one that reads the code itself to
determine the rules. For this, you need a somewhat more complex code
scanner, but that's not the hard part. The hard part is retrofitting the
declarations. Here, let me show a snipped of code that gets the idea across
better than I have so far:

*C_TEXT*($error_name)

$error_name:=*MethodCheck_ParameterCount* (*Count parameters*;3;3)
*If* ($error_name="")
$winref:=$1
$widget_name:=$2
$messages_array_pointer:=$3

*C_LONGINT*($previous_error_count)
$previous_error_count:=*ErrorStack_Count*

*MethodCheck_WindowReference* ($winref;*Value must be supplied*)
*MethodCheck_FormObjectNameInput* ($widget_name;*Value must be valid*)
*MethodCheck_PointerTypeSeries* ($messages_array_pointer;*Object array*)

*If* (*ErrorStack_Count* >$previous_error_count)
$error_name:=*ErrorStack_GetReportErrorName*



*End if End if If* ($error_name="")
// Main body of routine.
*End if *

Hopefully, that's not too cryptic or too dense. The idea is that a bunch of
pre-conditions are validated before the routine gets to work.
Basically, *ASSERT
*with extra control. Translated, the checks are:

*MethodCheck_ParameterCount*
A minimum of 3 parameters and a maximum of 3 parameters. I actually use
this code all the time. It's super handy for catching when the parameter
list is wrong. (Compiler should do this but it doesn't.) This also provides
a very tidy way of declaring optional parameters. In the example above,
there aren't any optionals.

*MethodCheck_WindowReference*
A value must be supplied, but it need not be a valid winref. I don't
remember, I think it defaults to the current window if it isn't valid.

*MethodCheck_FormObjectNameInput*
A form object name must be valid and must exist.

*MethodCheck_PointerTypeSeries*
The pointer needs to be to a variable of one of the specified types. In
this case, the list is just "object array". If you had a numeric array
pointer, you might specify longint array and real array.

The exact details may not matter much for this conversation. The general
idea is that inputs are validated in any of a few ways. Here are the names
of the validators:

*MethodCheck_BLOBInput *
*MethodCheck_DateInput *
*MethodCheck_DateRange *
*MethodCheck_DateSeries *
*MethodCheck_FilePathInput *
*MethodCheck_FolderPathInput *
*MethodCheck_FormEventInput *
*MethodCheck_FormNameInput *
*MethodCheck_FormObjectNameInput *
*MethodCheck_LongintInput *
*MethodCheck_LongintRange *
*MethodCheck_LongintSeries *
*MethodCheck_MethodNameInput *
*MethodCheck_ObjectInput *
*MethodCheck_ObjectTypeInput *
*MethodCheck_ObjectTypeSeries *
*MethodCheck_ParameterCount *
*MethodCheck_PictureInput *
*MethodCheck_PointerInput *
*MethodCheck_PointerIsAnAlpha *
*MethodCheck_PointerIsANumeric *
*MethodCheck_PointerSeries *
*MethodCheck_PointerTypeSeries *
*MethodCheck_RealInput *
*MethodCheck_RealRange *
*MethodCheck_RealSeries *
*MethodCheck_TextInput *
*MethodCheck_TextRange *
*MethodCheck_TextSeries *
*MethodCheck_TimeInput *
*MethodCheck_TimeRange *
*MethodCheck_TimeSeries *
*MethodCheck_WindowReference *

So, basically you can check by type, a range (1-7), or a series (list) like
("Mon";"Tue";"Wed").

And now, after my typical pithy introduction, I get to the point. With a
custom code scanner, you can read in these declarations and *generate
documentation based on the live code*. There is no disconnect possible
between the code and the docs because it's based 

Re: Methods, Components, Comments, and Tooltips

[Wayne Stewart via 4D_Tech]

Oops!

I forgot this bit:

  //  Threadsafe?
METHOD GET ATTRIBUTES($MethodNames_at{$CurrentMethod_i};$Attributes_o)
$ThreadSafe_t:=OB Get($Attributes_o;"preemptive")

Case of
  : ($ThreadSafe_t="capable")
$ThreadSafeSection_t:="\rPREEMPTIVE\r"

  : ($ThreadSafe_t="incapable")
$ThreadSafeSection_t:="\rCOOPERATIVE\r"

Else
$ThreadSafeSection_t:="\INDIFFERENT\r"

End case

Then just include $ThreadSafeSection_t in your comments somewhere.



Regards,

Wayne


[image: --]
Wayne Stewart
[image: http://]about.me/waynestewart



On 19 April 2017 at 16:32, Wayne Stewart  wrote:

> Hi,
>
> With all this talk about comments, I thought I would throw another 2¢ into
> the conversation.
>
> This is also useful for non components.
>
> I love the fact that 4D now displays tooltips over your methods.  However,
> sometimes the first few lines of the method are not too helpful.
>
> If you have anything written in the comments section of the explorer these
> are displayed instead (everyone should TURN OFF the automatic comment
> feature immediately).
>
> And if your code is in a component that is compiled, then only the
> Explorer Comments are displayed.
>
> Recently in Foundation I wrote a method to create comments based on the
> method header comments found there.  This was only possible because of the
> stick discipline Dave Batton used when creating these headers.
>
> Does anyone else miss Dave B?
>
> Anyway, to wind things up, why not write a 4D Method that reads those
> headers and creates the Explorer comments for you?
>
> Use a macro to create the header so it conforms to the pattern as you
> start each header and then Bob's your uncle.
>
> Here is what I use, you can modify it for your header pattern perhaps.
>
> NB.  Make sure your code starts below the header.  I use 4D Pop macro to
> declare my locals but the macro puts them at the first empty line, I just
> need to reposition them to below the header manually.
>
>
>
> Example Macro:
>
> 
>   // 
>   // Project Method:  --> ReturnType
>
>   // Description
>
>   // Access: Shared
>
>   // Parameters:
>   //   $1 : Type : Description
>   //   $x : Type : Description (optional)
>
>   // Returns:
>   //   $0 : Type : Description
>
>   // Created by Wayne Stewart ()
>   // wa...@4dsupport.guru
>   // 
>   
> 
>
>
>
>
> Code:
>
>   // 
>   // Project Method: FW_WriteComments {(Method Name; Do not use)}
>
>   // This method will create documentation comments
>   //   it is based on the assumption that you format your
>   //method header comments in the same manner as Foundation
>   //  The first paramater is just used to trigger the method
>   //   starting in a new process, you should not pass this parameter
>
>   // Access: Shared
>
>   // Parameters:
>   //   $1 : Text : Either pass "" to do all methods or a specific method
> name
>   //   $2 : Longint : Do not use this
>
>   // Created by Wayne Stewart
>   // 
>
> If (False)  //  Copy this to your Compiler Method!
>   C_TEXT(FW_WriteComments ;$1)
>   C_LONGINT(FW_WriteComments ;$2)
> End if
>
> C_TEXT($1)
> C_LONGINT($2;$ProcessID_i;$StackSize_i;$NumberOfMethods_
> i;$CurrentMethod_i;$Position_i)
> C_TEXT($MethodCode_t;$FirstChars_t;$MethodName_t)
>
> ARRAY TEXT($MethodNames_at;0)
> ARRAY TEXT($MethodCode_at;0)
> ARRAY TEXT($MethodComments_at;0)
>
> $StackSize_i:=0
>
> If (Count parameters=2)
>
>   METHOD GET PATHS(Path project method;$MethodNames_at)
>
>   $MethodName_t:=$1
>
>   If (Length($MethodName_t)>0)  //  A method name or prefix has been
> specified
>
> $NumberOfMethods_i:=Count in array($MethodNames_at;$MethodName_t)
>
> If ($NumberOfMethods_i=1)  // exactly one match (use this specific
> method)
>   ARRAY TEXT($MethodNames_at;0)
>   APPEND TO ARRAY($MethodNames_at;$MethodName_t)
> Else
>
>   $NumberOfMethods_i:=Size of array($MethodNames_at)
>   For ($CurrentMethod_i;$NumberOfMethods_i;1;-1)  // Go Backwards
> If ($MethodNames_at{$CurrentMethod_i}=($MethodName_t+"@"))
> Else
>   DELETE FROM ARRAY($MethodNames_at;$CurrentMethod_i)
> End if
>
>   End for
>
> End if
>
>
>
>   End if
>
>   $NumberOfMethods_i:=Size of array($MethodNames_at)
>
>   METHOD GET CODE($MethodNames_at;$MethodCode_at)
>
>   ARRAY TEXT($MethodComments_at;$NumberOfMethods_i)
>
>   For ($CurrentMethod_i;1;$NumberOfMethods_i)
> $MethodCode_t:=$MethodCode_at{$CurrentMethod_i}
>
> $Position_i:=Position("comment added and reserved by
> 4D.\r";$MethodCode_t)
>
> $MethodCode_t:=Substring($MethodCode_t;$Position_i+Length("comment
> added and reserved by 4D.\r"))
>
> $MethodCode_t:=Replace string($MethodCode_t;"\r  // Access:
> Shared\r";"")
> $MethodCode_t:=Replace 

Methods, Components, Comments, and Tooltips

[Wayne Stewart via 4D_Tech]

Hi,

With all this talk about comments, I thought I would throw another 2¢ into
the conversation.

This is also useful for non components.

I love the fact that 4D now displays tooltips over your methods.  However,
sometimes the first few lines of the method are not too helpful.

If you have anything written in the comments section of the explorer these
are displayed instead (everyone should TURN OFF the automatic comment
feature immediately).

And if your code is in a component that is compiled, then only the Explorer
Comments are displayed.

Recently in Foundation I wrote a method to create comments based on the
method header comments found there.  This was only possible because of the
stick discipline Dave Batton used when creating these headers.

Does anyone else miss Dave B?

Anyway, to wind things up, why not write a 4D Method that reads those
headers and creates the Explorer comments for you?

Use a macro to create the header so it conforms to the pattern as you start
each header and then Bob's your uncle.

Here is what I use, you can modify it for your header pattern perhaps.

NB.  Make sure your code starts below the header.  I use 4D Pop macro to
declare my locals but the macro puts them at the first empty line, I just
need to reposition them to below the header manually.



Example Macro:


  // 
  // Project Method:  --> ReturnType

  // Description

  // Access: Shared

  // Parameters:
  //   $1 : Type : Description
  //   $x : Type : Description (optional)

  // Returns:
  //   $0 : Type : Description

  // Created by Wayne Stewart ()
  // wa...@4dsupport.guru
  // 
  





Code:

  // 
  // Project Method: FW_WriteComments {(Method Name; Do not use)}

  // This method will create documentation comments
  //   it is based on the assumption that you format your
  //method header comments in the same manner as Foundation
  //  The first paramater is just used to trigger the method
  //   starting in a new process, you should not pass this parameter

  // Access: Shared

  // Parameters:
  //   $1 : Text : Either pass "" to do all methods or a specific method
name
  //   $2 : Longint : Do not use this

  // Created by Wayne Stewart
  // 

If (False)  //  Copy this to your Compiler Method!
  C_TEXT(FW_WriteComments ;$1)
  C_LONGINT(FW_WriteComments ;$2)
End if

C_TEXT($1)
C_LONGINT($2;$ProcessID_i;$StackSize_i;$NumberOfMethods_i;$CurrentMethod_i;$Position_i)
C_TEXT($MethodCode_t;$FirstChars_t;$MethodName_t)

ARRAY TEXT($MethodNames_at;0)
ARRAY TEXT($MethodCode_at;0)
ARRAY TEXT($MethodComments_at;0)

$StackSize_i:=0

If (Count parameters=2)

  METHOD GET PATHS(Path project method;$MethodNames_at)

  $MethodName_t:=$1

  If (Length($MethodName_t)>0)  //  A method name or prefix has been
specified

$NumberOfMethods_i:=Count in array($MethodNames_at;$MethodName_t)

If ($NumberOfMethods_i=1)  // exactly one match (use this specific
method)
  ARRAY TEXT($MethodNames_at;0)
  APPEND TO ARRAY($MethodNames_at;$MethodName_t)
Else

  $NumberOfMethods_i:=Size of array($MethodNames_at)
  For ($CurrentMethod_i;$NumberOfMethods_i;1;-1)  // Go Backwards
If ($MethodNames_at{$CurrentMethod_i}=($MethodName_t+"@"))
Else
  DELETE FROM ARRAY($MethodNames_at;$CurrentMethod_i)
End if

  End for

End if



  End if

  $NumberOfMethods_i:=Size of array($MethodNames_at)

  METHOD GET CODE($MethodNames_at;$MethodCode_at)

  ARRAY TEXT($MethodComments_at;$NumberOfMethods_i)

  For ($CurrentMethod_i;1;$NumberOfMethods_i)
$MethodCode_t:=$MethodCode_at{$CurrentMethod_i}

$Position_i:=Position("comment added and reserved by
4D.\r";$MethodCode_t)

$MethodCode_t:=Substring($MethodCode_t;$Position_i+Length("comment
added and reserved by 4D.\r"))

$MethodCode_t:=Replace string($MethodCode_t;"\r  // Access:
Shared\r";"")
$MethodCode_t:=Replace string($MethodCode_t;"  //
\r";"")
$MethodCode_t:=Replace string($MethodCode_t;"//
\r";"")

$MethodCode_t:=Replace string($MethodCode_t;"  // Project Method: ";"")
$MethodCode_t:=Replace string($MethodCode_t;"// Project Method: ";"")

$MethodCode_t:=Replace string($MethodCode_t;"  // ";"")
$MethodCode_t:=Replace string($MethodCode_t;"// ";"")

$Position_i:=Position("Created by";$MethodCode_t)

$MethodCode_t:=Substring($MethodCode_t;1;($Position_i-3))

$FirstChars_t:=Substring($MethodCode_t;1;2)
While ($FirstChars_t="\r\r")
  $MethodCode_t:=Substring($MethodCode_t;2)
  $FirstChars_t:=Substring($MethodCode_t;1;2)
End while

$MethodComments_at{$CurrentMethod_i}:=$MethodCode_t


  End for

  METHOD SET COMMENTS($MethodNames_at;$MethodComments_at)