Improved documentation - add cube.scad - overview - ...

[dimitrydhondt]

Hi there

FIrst of all: Thank you very much for creating a unit testing library for openSCAD. If physical objects are becoming code, that code must be kept clean, and covered by unit tests for sure! :-)

In trying to use the module I find myself working through the sources to understand how it works. It would be nice if the documentation was more forthcoming.

Things I bump into are:

• In the docs an example is given on how to unit test a simple cube.scad file. The content to that file is not given, leaving it to the user to guess what is inside that. More specifically 'is that file supposed to contain a module? or not?' - as the documentation then continues to imoprt it as a "3D module".
• What is the basic operation of the tool? I find on other forums a brief description giving me clues. Apparently modules are run via the openscad command to generate STL, and this would than be the basis for the test. Adding this kind of high-level idea on how the library functions should certainly help people to start using it.
• In general the documentation is too brief to lead a potential user to understand enough to start using the lib.

Perhaps I can contribute by improving the documentation a bit, as my perspective is currently a beginner's perspective on the module?

[HopefulLlama]

Hi,

In the docs an example is given on how to unit test a simple cube.scad file. The content to that file is not given, leaving it to the user to guess what is inside that. More specifically 'is that file supposed to contain a module? or not?' - as the documentation then continues to imoprt it as a "3D module".

I think adding the example cube.scad file would be great to give some context to the example in the README. I can take a look at doing so

What is the basic operation of the tool? I find on other forums a brief description giving me clues. Apparently modules are run via the openscad command to generate STL, and this would than be the basis for the test. Adding this kind of high-level idea on how the library functions should certainly help people to start using it.

The detailing in the forum is the implementation detail, and shouldn't concern the actual usage of the tool. The steps in the README cover how to install and use the library, however I think there's a gap in how to meaningfully use the library in order to make some useful tests.

To quickly answer this, essentially UnitTestSCAD aims to help build the assertions, such as "Is the model's width 5 units?", and the intention is that this should be used in tandem with another unit testing library (jest, jasmine) to actually build the tests themselves.

While I wouldn't mind a contribution, I can also take a look at building out the doc a bit more myself.

[HopefulLlama]

There's also the API Documentation which goes into further details, but unfortunately the formatting is pretty horrible and I hate it.