Documentation

[José Roca]

I know that writing documentation is a pain, but it is absolutely needed unless you want to restrict the use of your compiler to a few users. If you delay it until you think that you have finished the job with the compiler, then you never will do it because you will always find something to add, fix or change.

When I wrote my framework for FreeBasic, each time that I added a new procedure the next step was to document it. If later I modified it, I also modified the documentation. With about 4,200 entries, if I had to write it now entirely I probably will never do it. Better to spend some time everyday that hundreds of hours later.

[Brian Alvarez]

Agreed.

[Charles Pegge]

Welcome to our forum, Brian.

Q & A plays a major role in creating the OxygenBasic library, since there is no formal framework, and it has grown 'organically' based on meeting various coding challenges.

I'm looking at Doxygen as a possible standard for embedded documentation. Any views on this? The name fits

[Brian Alvarez]

Charles, i like the idea of building an option for my PluriBASIC to generate Oxygen code, in fact, its is already in place and pretty advanced. It is now generating a vast language but i kind of needed to be guessing, because there is no definitive syntax.

 I am also afraid that once i finish an area, the syntax could change and i would need to re-do it. I personally do not mind what syntax you use, i can adapt the engine that PluriBASIC uses to generate whatever code needed, but i do need it to be stable.

 One of the reasons i made my own functions for PHP was that it likes deprecating stuff, and my engine adapts to whatever version of PHP. So, I would suggest you to decide the final syntax, add it and any future features for a statement to be added as extra, and not as "instead of".

 I understand the problems that developing software and at the same time documenting it represents, because i have the same problem, but, to build on top of something, the cimentation must be well stablished.

 What do you think?

[Charles Pegge]

The core syntax is well established, Brian, and the trend is towards creating additional 'freedom of expression', often by adding default value parameters. It's my bedtime now but I would like to mention a few leading edges which are not quite solid yet...

[Brian Alvarez]

 Perfect, i will start building on what you have.

 I will check your examples, to learn from them. Do we already have something to "redim preserve"?

[Charles Pegge]

Redim always preserves content, unless you are reducing the size of the array, of course.

Redim is not hard-coded, it is implemented as a macro, and uses a string as the array buffer

You can override just about any of O2's core definitions, if you need to, as a developer.


On the leading edge, where things are a little uncertain, are variadic macros, and the use of MSVCRT to take over some of the RTL32/RTL64 functions. I'm also taking O2 through self-compiling, so the internal architecture of O2 is likely to change quite a bit.