On 03.05.20 17:43, Bruno Boettcher wrote:

I have not found any existing general-use documentation tool
with OpenSCAD support.

There's a couple of things people built for their libs,
but what I would like to see is direct support in OpenSCAD
via syntax like for example python doc strings.

If the parsing part is taken care of, it should be much
easier to integrate with existing documentation generators.

This would need a bit more thinking and work initially, but
should be able to produce a much more stable solution in
the long run.

ciao,
Torsten.

On 2020-05-03 17:43, Bruno Boettcher wrote:

The only practical way to keep such documentation up-to-date is if you
can generate it at least partly automatically, so your idea is in my
opinion the correct one. A much used documentation-system is doxygen
(http://www.doxygen.nl/), with support for several languages.  It can
generate HTML or other formats.

Without support for a particular language such as scad, your choice is
between implementing the support yourself, or generating input in a
format that doxygen already understands. But at least you need a way to
extract the relevant information. That is something I believe OpenSCAD
does not have but might benefit from.

I had a similar issue with AngelCAD, but the AngelScript language
supports extracting detailed information from
built-in or application-defined functions/classes, so it is relatively
easy to generate doxygen-compatible input based on that and keep it up
to date. Doing that my result was
https://arnholm.github.io/angelcad-docs/docs/annotated.html

Maybe you can modify the OpenSCAD language parser.

Carsten Arnholm

I also scrape markdown comments from functions and modules with Python to
auto document my library. I just start  them with //!, so it it is very
easy. I don't think it needs any support from OpenSCAD as lots of other
languages don't have it but are still documented, for example C++.

I don't have any utilities for joining things though. All my parts have
convenient origins and sufficient property functions to get their
dimensions and place them plus modules to place things like fasteners
relative to them. So I have no problem making assemblies out of them.

On Sun, 3 May 2020 at 18:00, arnholm@arnholm.org wrote:

On 03.05.20 21:30, nop head wrote:

That's true, but having it attached to the parsed data
would also allow it to be used from inside the OpenSCAD
GUI. Which is not going to happen with random comments
where people are using different tools (which does work
totally fine for a specific project of cause).

ciao,
Torsten.

hello!
could you be more specific? i found that library, but eluded the part about
documentation?

anyway i gave it a quick hack, in case someone is interested,
https://github.com/nohkumado/openscadpod but if bosl does that already not
need to continue.... just need to find out how it does it...

Am So., 3. Mai 2020 um 18:38 Uhr schrieb adrianv avm4@cornell.edu:

--
ciao
Bruno

---==========
http://nohkumado.eu/, http://bboett.free.frhttp://aikido.nohkumado.eu/,
http://bboett.free.fr
http://aikido.zorn.free.fr

The link I gave

https://github.com/revarbat/BOSL2/wiki

goes to a wiki which documents the BOSL2 library and is entirely
auto-generated from the BOSL2 source code using the comments that precede
the functions and modules.  If you download the source code and look at it
you will see the comments.  Revar wrote scripts that produce the wiki from
the code.  I have never run them myself and don't know the details, but I
assume they are somewhere in the code base.

bboett wrote

--
Sent from: http://forum.openscad.org/

The BOSL2 docs format is described here:
https://github.com/revarbat/BOSL2/blob/master/WRITING_DOCS.md

The processing scripts are:
https://github.com/revarbat/BOSL2/blob/master/scripts/docs_gen.py
https://github.com/revarbat/BOSL2/blob/master/scripts/make_all_docs.sh

-Revar

One of the questions that needs a firm answer is "what do you want to
document?"

If it is just unstructured text from a comment block at the start of
each module, that is one thing.
If you want "where used" that is another.
Do you want to know the meaning of each argument to a module?
(parameters vs output)
Do you want a list of modules in a file?
Do you want a list of global constants and their values?
Do you want to know who was the author of the code?
What else? General comments about the file? General instructions? Version?

It is pretty useless to generate "50 ways to document your model" if the
goal is to encourage sharing of models or to have a workable
documentation structure that can be community supported. Even if the
reporting methods are not available, a spec about how to document a file
with its modules would be worthwhile.
Once you know what you have to parse, parsing it gets easier.
Once you know what the documentation elements MUST be in order to get
parsed, one can write module documentation even if it can not be parsed
today with some assurance that it will be able to be used in the future.

The "correct" way  should be clear to everyone so that it is possible to
incorporate modules into a model without having to redo the
documentation lines to have it automatically incorporated into the
project's documentation.

JavaDoc has a well defined way to document packages, classes and methods
using annotations (@tags) in specially identified comment blocks in
code  - /** / as opposed to / */ which are not included in
documentation (implementation details that may change without changing
the functionality).

No one would think of designing their own schema for Java documentation.
https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

There is one Open Source JavaDoc parse that might be useful in creating
a JavaDoc-like tool for
OpenSCAD.https://github.com/javaparser/javaparser/blob/master/readme.md
https://github.com/javaparser/javaparser/blob/master/readme.md
Might be more. But it might be possible to customize their parser to
support the extra annotations required to document a CAD software rather
than a Java program.
Not familiar with C++ but it looks like JavaDoc
https://developer.lsst.io/cpp/api-docs.html

Python documentation looks pretty weird compared to Java and C. Perhaps
someone else might be better qualified to discuss how it might apply to
OpenSCAD.

Ron

On 2020-05-03 1:00 p.m., arnholm@arnholm.org wrote:

--
Ron Wheeler
Artifact Software
438-345-3369
rwheeler@artifact-software.com