Wiki improvements

Forum for discussion about the documentation project.
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: Wiki improvements

Postby fxm » May 12, 2018 8:28

After sticking in Documentation forum the pedagogic topic:
- How to Manage a Critical Section of the code of a Thread in FB

I just added (sticking) the second pedagogic topic (by rewording and completing an already existing topic in the Documentation forum):
- How to Overload the Operator '->' (ptr to member access) and Build a Smart Pointer in FB

Good reading !

(next document in progress: How to Solve the Flickering Issue when Refreshing a Window in FB Graphics Mode)
coderJeff
Site Admin
Posts: 2716
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » May 12, 2018 14:22

paul doe wrote:Can the 'report post' function of the forum be used for this purpose? I mean, it allows one to state the reason for the report, so it can also be used to 'report' a useful/insightful post/thread to be added to the Documentation forum, no?

@paul doe, the typical function of the 'report post' function is to report 'bad' posts, though I suppose it could be used to highlight 'good' or 'special' posts. Reported posts will show up in the moderator's log and remain there until the report is closed.
fxm wrote:I'm wondering about the well-identified bugs (by bug reports)...

@fxm, I understand your point, how best to document long time bugs or missing features. As a broad guideline, wiki should document what the compiler does, and in some cases, what is intended.

What about a wiki page for "Known Bugs"? Rather than document the bugs on each topic page, just provide a link in the "See Also" section.

There are some users (like MrSwiss) that seem to read the documentation like it is a rigid language specification. For example, the negate operator on literals with suffixes "bug". Change the documentation to match what the compiler does and it becomes a feature request. i.e. bug is within the documentation, not the compiler.

I think 3 related wiki improvements could be:
1) The "Note:..." additions, probably feel like they need to stand out at the time they are added, but I think they could just be added as normal documentation as part of the general description.
2) "Since/before version fbc #.##" can typically be removed, maybe unless it is the current development version. i.e. fbc 1.06
3) make positive assertions about how the keyword works, rather than negative ones. Just describe what the keyword can do and not the 1000's of things it can't do.

Yeah, I want to give good information to users also. I also want to leave the possibility for developers to make changes, sometimes compatibility breaking changes, to fix and improve the compiler.
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: Wiki improvements

Postby fxm » May 12, 2018 18:35

fxm wrote:After sticking in Documentation forum the pedagogic topic:
- How to Manage a Critical Section of the code of a Thread in FB

I just added (sticking) the second pedagogic topic (by rewording and completing an already existing topic in the Documentation forum):
- How to Overload the Operator '->' (ptr to member access) and Build a Smart Pointer in FB

Third pedagogic topic (by copying, reformulating and completing one of my already existing posts on the beginners forum):
How to Solve the Flickering Issue when Refreshing a Window in FB Graphics Mode
badidea
Posts: 1002
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Wiki improvements

Postby badidea » May 12, 2018 23:15

By accident I ended up here: https://www.freebasic.net/wiki/wikka.ph ... roPgFileIO
The example code is horrible. If the introduction (4 ways to to file I/O) is still useful, I can clean up the code. Otherwise, this page can be removed I think.
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: Wiki improvements

Postby fxm » May 13, 2018 8:48

You're right for the quality of the code (I will not say more because I think I know the author).
You are free to re-code it (as you propose), and even to add a function of file creation by the program itself at the request of the user, who would specify the name and size for example.
MrSwiss
Posts: 2811
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Postby MrSwiss » May 13, 2018 12:13

@fxm,

I've got a proposal, regarding the latest changes to this sub-forum (stickies).
Since I think, that by now, we already have *to many* of them:
  • create a new topic (INDEX of ... )
  • use it to place only LINKS and maybe a short explanation of topic(s) covered.
  • after writing to it, lock it (no comments allowed)
  • make only the INDEX sticky (not the threads pointed to!)
This would prevent cluttering up the DocForum, with stickies ...
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: Wiki improvements

Postby fxm » May 13, 2018 12:23

OK.
This is what was already planned, perhaps in the longer term:
coderJeff wrote:If a number of topics like this are identified and moved here, I suggest making one sticky (pinned) topic that links to the individual topics.
MrSwiss
Posts: 2811
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Postby MrSwiss » May 13, 2018 12:29

fxm wrote:perhaps in the longer term:
No, I think it should be done NOW (reason: less work, to make the change, right now!).

The more changes needed, the less interest to change, will exist (to much work!).
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: Wiki improvements

Postby fxm » May 13, 2018 12:40

My "OK" meant for me: "Yes, right now".
MrSwiss
Posts: 2811
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Postby MrSwiss » May 13, 2018 12:48

Well, you know, the sentence following the OK, seemed to indicate otherwise ...
Maybe in writing we have to be somewhat more clear, than by discussing things
face to face, when such misunderstandings are easier/quicker resolved ...
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: Wiki improvements

Postby fxm » May 13, 2018 14:58

MrSwiss wrote:@fxm,

I've got a proposal, regarding the latest changes to this sub-forum (stickies).
Since I think, that by now, we already have *to many* of them:
  • create a new topic (INDEX of ... )
  • use it to place only LINKS and maybe a short explanation of topic(s) covered.
  • after writing to it, lock it (no comments allowed)
  • make only the INDEX sticky (not the threads pointed to!)
This would prevent cluttering up the DocForum, with stickies ...
Done.

I hope this will give all users the desire to read them and also to propose other articles to develop from existing topics.
Because starting from scratch is a big job, especially for advanced features, but we will have maybe not the choice for some articles:
fxm wrote:I could probably myself add other topics such as "Dynamic allocation of memory", "Advanced UDT (with constructors / operators / destructor)", "Inheritance and polymorphism", ...
But it's already a lot of work to write such threads in the forum that it would be even more in the documentation, because having in addition to respect the formatting of the pages and if possible in a good English concise and precise at the same time.
coderJeff
Site Admin
Posts: 2716
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » May 13, 2018 17:21

fxm, looks good, nice!
srvaldez
Posts: 1672
Joined: Sep 25, 2005 21:54

Re: Wiki improvements

Postby srvaldez » May 13, 2018 22:32

hello fxm :-)
please have a look at this post by José Roca http://www.jose.it-berater.org/smfforum ... 9#msg22959
José Roca wrote:
If we return a CWstr as CWstr, the data is still valid, even if the local CWstr goes out of scope, because we return it as CWstr. But then some FreeBASIC commands complain of an "invalid data type" ..


When you return a CWSTR, CBSTR, STRING, WSTRING or string literal in a function that has a CWSTR as the return type, the compiler creates a temporary CWSTR and calls its appropriate constructor. It is important to remember that you must use RETURN <CWSTR or CBSTR> instead of FUNCTION = <CWSTR or CBSTR>. The reason is that when we use RETURN the constructor is called BEFORE the local variable goes out of scope, whereas if we use FUNCTION =, the constructor of the temporry CWSTR to be returned is called AFTER the local variable has been destroyed, making impossible to copy it. I don't know if this beavior of FUNCTION = is a bug or intentional (if it is intentional, it doesn't make sense to me).

it may be useful to have that information in the help file.
fxm
Posts: 8424
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: Wiki improvements

Postby fxm » May 14, 2018 5:58

I do not know CWSTR.inc nor the CWSTR class structure, but there is no FreeBASIC bug (IMHO) when using 'FUNCTION =' to return an object from a function.

The only precaution to take when we use 'FUNCTION = variable' is simply never to modify the value of the variable after this code line 'FUNCTION = variable' (which calls the copy operator), because this variable modification will not be taken into account in the return value:

Code: Select all

Function f () As Integer
  Dim As Integer I
  I = 1
  Function = I
  I = 2
End Function

Print f() ' print "1" but not "2"

Sleep

Note: When we use 'FUNCTION = variable', the constructor for the return value is always called the first in the executed function code, whatever the effective location of the code line 'FUNCTION = variable'. Only the copy operator's call is triggered by the location of this code line.

Note: In addition, I do not quite see the relationship between the answer above (which I dispute) and the remark that seems to question the right operation of the CAST operator (implicitly or explicitly called?).
dodicat
Posts: 5221
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Wiki improvements

Postby dodicat » May 14, 2018 9:35

Unless you deliberately do something silly of course.

Code: Select all

 



Function f () As any ptr
  Dim As any ptr I
  I = imagecreate(300,300)
  circle I,(150,150),50
  Function = I
 ' I=0  'this saves a crash
  imagedestroy I
End Function


screen 19
dim as integer x,y
dim as any ptr z=f()
imageinfo z,x,y
print x,y,z

put (300,300),z,pset


Sleep 

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 1 guest