Improve documentation

[woollybah]

Some of the modules could do with better documentation, especially examples to help understand general usage better.

Here's is a list of modules and what we feel are required still. They will be checked off as the work is done. Feel free to suggest more, which we can add to the list. Help is also welcome ;-)

Note that documentation and examples are provided in the following ways :

• Inline bbdoc comments. One for every item that wants to appear in the generated documentation.
• A module intro.bbdoc file. This is added to the top of the documentation.
• Example files go in the doc folder. They should be named, in lowercase, after the Type, function or Method the example represents. For Type methods and functions, the filename should also be prefixed with the Type name. So, for TBank.Create, you would call the file tbank_create.bmx.

BRL.Audio

• [ ] Add more TChannel examples.

BRL.Bank

• [ ] Add more TBank examples.

BRL.Blitz

• [ ] Revisit keyword examples.

BRL.Clipboard

• [ ] Add a intro.bbdoc or general notes about using the clipboard.
• [ ] Add examples

BRL.Json

• [ ] Add a intro.bbdoc or general notes about Json.
• [ ] Add examples

BRL.LinkedList

• [ ] Add more function examples.
• [ ] Add TList examples.

BRL.Matrix

• [ ] Add intro.bbdoc with introduction to matrices.
• [ ] Add examples.

BRL.Quaternion

• [ ] Add intro.bbdoc with introduction to quaternions.
• [ ] Add examples.

BRL.StringBuilder - @woollybah

• [x] Add intro.bbdoc with introduction.
• [x] Add examples.

BRL.Stream

• [ ] Add more example.

BRL.Vector

• [ ] Add intro.bbdoc with introduction to vectors.
• [ ] Complete SVec2 examples and duplicate for SVec2F and SVec2I
• [ ] Add examples for SVec3

BRL.Volumes

• [ ] Add TVolume example.

BRL.XML

• [ ] Add a intro.bbdoc or general notes about XML.
• [ ] Add more examples

[HurryStarfish]

BRL.Blitz contains a lot of code examples, especially for all the keywords. Unfortunately, a lot of them are badly out of date, containing non-strict code, inaccurate information, poor formatting etc. These need a rework at some point.

[woollybah]

We should also have a "See Also" section at the foot of each intro.bbdoc, referring to other related modules/types.

[GWRon]

So it needs an automated way to reference stuff. Within bbdoc maybe add "seealso:" or even more stuff to cross-"promote" other features.

PS: check your spam folder ;-)

[woollybah]

I'm happy to accept PR's for documentation/examples. It is not one of my favourite chores...

[GWRon]

Would you mind rendering a list of todo modules so we could collaboratively work along this list?

[woollybah]

There's a reasonably long list in the initial issue post. I can put names next to modules once someone volunteers to work on one.

For the "geometry" modules (vector, matrix and quaternion), it would be nice if the intro.bbdoc was also an introduction to the subject, maybe with diagrams too. This would lead nicely into specific examples within the structs themselves.

[GWRon]

So you think it is necessary to explain vectors, matrices and so on (in detail)? Think we should not play Wikipedia and instead link to that there (aside to some basic explanation).

Same goes for the whole addition, dot product... I say this as it is a lot of effort to create diagrams, write (useful) texts ... for something people might just skip.

Or are you talking about something different in the "intro"?

[GWRon]

BRL.LinkedList

• [ ] Add more function examples.
• [ ] Add TList examples.

What is meant with "function examples" - compared to "TList examples". The one is giving examples for specific functions/methods of TList - and the other.... generic examples on when to use TLists or what to use them for?

[GWRon]

Also: should we try to use the "procedural" or the "OOP" interface?

I mean:

PauseChannel(myChannel)
ResumeChannel(myChannel)
'vs
myChannel.SetPaused(true)
myChannel.SetPaused(false)

[GWRon]

The above question is still open. Just thought about starting with something simple: TList but there is ListAddLast() and list.AddLast() which we can use.

For stringbuilder.mod you / @woollybah gave examples for the "OOP interface" (sb.Append()).

Which way should we prefer to go? Or provide the same example for both commands (if there is a procedural one) ?

[GWRon]

Added a PR - decided to write both: procedural and oop-eque doc/examples

[GWRon]

When writing documentation and there are missing "procedural functions" I try to add them - like in the latest PR.

[GWRon]

Add more TChannel examples. Hmm.... there are examples ... what exactly do you mean with "more". Suggestions?

[GWRon]

wrote the xml-doc part 7 months ago but it was not added yet -- will link it here, so it is not forgotten: https://gist.github.com/GWRon/609279d762f36472e33625d6eabb8cd4