OpenEuphoria

Good documentation

• Posted by Shian_Lee Apr 01, 2015
• 2252 views

(It might be not fair to ask, but at least to mention).

Intro:
Long time ago I was programming in MS-QuickBasic. I could use this language since it came with good (let's say amazing) documentation.

Few years ago I was programming in MS-VBA (Visual-Basic for Applications)... The documentation was simply terrible. I was looking for description for specific objects - and that's all I found: a description. There was no example at all. No tip. Nothing. I was moving in circles inside the huge manual, and eventually returned to the same point (subject) after an hour of search.
MS-VBA manual did not supply examples or tips for the most important topics - only description.

In other words MS-VBA (unlike MS-QuickBasic) behaves like this:

for i = 1 to 10 do         -- count from 1 to 10 
   printf(1, "\n%d", i)    -- print the number on the screen on a new line 
end for                    -- return to counter 

The documentation in the above code describes the operation, nothing else.
I found the MS-VBA manual totally useless. again: absolutely useless. misleading. Huge manual with no valuable info - especially on the hot topics. All I could do then is to try to cheat the database-objects by assigning all kinds of experimental SQL strings to them - instead of using the objects properly, etc.

Chapter 1:
See for example the topic arcsin in Euphoria manual:

8.24.3.6 arcsin

include std/math.e
namespace math
public function arcsin(trig_range x)

Return an angle given its sine.

Parameters:
value : an object, each atom in which will be acted upon.

Returns:
An object, the same shape as value. When value is an atom, the result is an atom, an angle whose sine is value.

Errors:
If any atom in value is not in the -1..1 range, it cannot be the sine of a real number, and an error occurs.

Comments:
A value between -PI/2 and +PI/2 (radians) inclusive will be returned.
This function may be applied to an atom or to all elements of a sequence.
arcsin() is not as fast as arctan().

Example 1:

s = arcsin({-1,0,1})
s is {-1.570796327, 0, 1.570796327}

See Also:
arccos, arccos, sin

... I know it's too much to ask, but, an average proud elementary school senior (like me) would appreciate to find:

1. Practical example(s): some truly useful example of real life use.
2. Tip(s): I didn't learn trigonometry, so can you give me a hint? cool and valuable info that only the professors in university can think of?
   
   

Chapter 2:
arcsin() is just an example, since it is a very useful function if you've learned trigonometry. But many new users would love to see a practical example(s) and tip(s) for, let's say: and_bits(). What can I do with and_bits()? hot Tips where and_bits() can save my life or at least make them better.

This applies to any other topic.

Bibliography:

1. Microsoft QuickBasic 4.5
2. Microsoft Visual-Basic for Applications (VBA)