Something like:

$  Runsun Pan, PhD

$ libs:

doctest ,

faces ( git ),

offline doc ( git ),

runscad.py( 1 , 2 , git ),

synwrite( 1 , 2 );

$ tips:

hash( 1 , 2 ),

sweep ,

var( 1 , 2 ),

lerp ,

animGif ,

precision( 1 , 2 ),

xl-control

--
View this message in context: http://forum.openscad.org/api-in-json-format-tp15418p15419.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

On 01/02/2016 07:13 PM, runsun wrote:

I'm not aware of any existing file.

Yes, it would be useful for a number of other cases too, like as input
for https://github.com/openscad/openscad/pull/905 and maybe also for the
cheatsheet.

Some additional data that could be included:

• general

  • version of the description file itself
  • version of OpenSCAD the description refers to

• function/module

  • link to manual

• parameters

  • data type of parameter
  • mandatory / optional parameter

There's also another option, but that's probably too much work for the
short term... add the information to the code itself and let OpenSCAD
generate that info via some special command line switch.

ciao,
Torsten.

Thx for the inputs. Will take into considerations.

The journey into SynWrite calltip feature looks promising. I've made this
possible: when user type "cube(", the output panel will show it's parameter
definition:

http://forum.openscad.org/file/n15457/synwrite_calltip.png

I'm still working on how this is gonna play out, but most likely, once it's
done, users can have this feature by simply import a python plugin.

Here is the current json structure that I am using. Currently it has only
cube() and sphere(). Will keep modifying the structure along the way.

It's currently written inside the python on_key plugin. Eventually it has to
be a stand-alone json file.

$  Runsun Pan, PhD

$ libs:

doctest ,

faces ( git ),

offline doc ( git ),

runscad.py( 1 , 2 , git ),

synwrite( 1 , 2 );

$ tips:

hash( 1 , 2 ),

sweep ,

var( 1 , 2 ),

lerp ,

animGif ,

precision( 1 , 2 ),

xl-control

--
View this message in context: http://forum.openscad.org/api-in-json-format-tp15418p15457.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

This is in response to Neon22's suggestion for a language extension, to add
a doc string to function and module definitions.

The "Customizer GUI" project is already defining a syntax for adding a doc
string to variable definitions. Check out this example:
https://github.com/openscad/openscad/blob/model-meta-data3/examples/Parametric/sign.scad

Following that example, the syntax would be

@Description("doc string")
module foo() {
};

This syntax works fine with OpenSCAD2.

This opens up the question of whether we want to add a syntax for adding
doc strings and type annotations to each parameter of a function or module
definition.

Type annotations in particular are a big can of worms, especially if you
want them to be accurate, given the way some primitive functions and
modules are designed. How would you specify the type of 'min'? The
arguments are either a variable number of numeric arguments, or a single
argument which is a list of numbers. Up to this point, I've considered that
adding type annotations to OpenSCAD is not worth it, given the complexity
of the type language we'd need.

On 4 January 2016 at 00:49, Neon22 mschafer@wireframe.biz wrote:

doug.moen wrote

That's pretty cool. What is the meaning of

@Parameter([10, 20, 30, 50, 100])

Does it mean only the listed values are allowed ?

How about this:

@type("int")

@type("number", "list")

In the api that I wrote in previous post, I use:

to indicate that both list and number are allowed.

OpenSCAD mailing list
Discuss@.openscad
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org

$  Runsun Pan, PhD

$ libs:

doctest ,

faces ( git ),

offline doc ( git ),

runscad.py( 1 , 2 , git ),

synwrite( 1 , 2 );

$ tips:

hash( 1 , 2 ),

sweep ,

var( 1 , 2 ),

lerp ,

animGif ,

precision( 1 , 2 ),

xl-control

--
View this message in context: http://forum.openscad.org/api-in-json-format-tp15418p15468.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

In order for an IDE editor to reliably show you hints about the names and
types of parameters, you need a strongly typed language, and you need the
IDE to parse and compile the code being edited in order to collect type
information for functions you might be calling. OpenSCAD isn't designed to
be a strongly typed language, so I'm not optimistic about this kind of
project succeeding.

If your only goal is to present information about built-in functions and
modules, and you don't worry about presenting hints for functions and
modules that are locally defined, or defined via include <f> or use <f>,
then the problem is much easier. In this case, we don't need type
annotations in the language at all.

In OpenSCAD2, the problem gets harder, because objects are first class
values, and you can write obj.f(x). So the IDE needs to know the type of
'obj', which could be passed as a parameter, or returned as a result from
another function call.

On 4 January 2016 at 09:40, runsun runsun@gmail.com wrote:

On Mon, 4 Jan 2016 10:04:51 -0500
doug moen doug@moens.org wrote:

That's an "or" not an "and" I think you'll find.

If you have the parse tree you know the set of valid types for any given
parameter and the resulting returned type. That may be quite a long list
and you may need to sort it by interest or represent it cleverly.

Alan

I kind of getting lost about what you said. But, that's ok.

Don't know if this is helpful but I've been using type inspection, type
casting etc in my lib for quite a while:

The type-checking has been a very crucial part of my lib, even geometric
stuff like points, lines and planes can be type-checked:

$  Runsun Pan, PhD

$ libs:

doctest ,

faces ( git ),

offline doc ( git ),

runscad.py( 1 , 2 , git ),

synwrite( 1 , 2 );

$ tips:

hash( 1 , 2 ),

sweep ,

var( 1 , 2 ),

lerp ,

animGif ,

precision( 1 , 2 ),

xl-control

--
View this message in context: http://forum.openscad.org/api-in-json-format-tp15418p15473.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

On 01/04/2016 03:40 PM, runsun wrote:

Yes, this is basically the basis for modeling the functionality
that the Thingiverse Customizer provides by adding comments to the
scad script.
See the github comment for short example screencasts
https://github.com/openscad/openscad/issues/722#issuecomment-69521189

The meta data definition would allow a long list of other
use-cases, not only the customizer parameter specification.
I've started to collect some of the use cases for different
types of annotations in the wiki:
https://github.com/openscad/openscad/wiki/Meta-Data-Use-Cases

The prototype implementation in branch model-meta-data3 uses
the Java Annotation like syntax as shown above, if it would
make things easier for other cases (e.g. OpenSCAD2) it should
be quite simple to use a different syntax...

ciao,
Torsten.

On 01/04/2016 06:49 AM, Neon22 wrote:

I think that would be possible with current OpenSCAD too, it
would simply require all new code that uses it to use the new
OpenSCAD version - which is pretty normal.

It seems to be some kind of convention to use triple " to mark
the docstring, so maybe that would make sense here too.
I guess the idea with that is to allow various markup in that
section, including the use of normal single quotes.

Although for current OpenSCAD, that would probably just allow
the syntax as we have no way for introspection or setting some
object field to make it available at runtime (some simple
solution like a docstring() function returning the doc of the
current module could be added, but I'm not sure that's very
useful).

It still would define a standard way for adding documentation,
which is a good thing to have. It might even allow to use
documentation generation tools like Sphinx to run on OpenSCAD
code.

ciao,
Torsten.

Hi Torsten.

Sphinx is specifically designed for Python, so it requires the python """
string literal syntax, as you have noted. We'd have to extend the OpenSCAD
syntax to make it Sphinx compatible.

Or we could use Doxygen, which should work with OpenSCAD right now, with no
language extensions, since Doxygen was designed for C++, and embeds
documentation in C++ comments, which comment syntax is also supported by
OpenSCAD.

Sphinx uses ReStructuredText as its text markup language: RST is mostly
only used by the Python community. Doxygen uses MarkDown, which will be
familiar to a lot of OpenSCAD developers since github also uses MarkDown.
In fact, Doxygen will even process the README.md file at the root of your
project tree, which is also processed by github.

So I think doxygen is a better starting point for an OpenSCAD inline
documentation tool.

On 4 January 2016 at 11:25, Torsten Paul Torsten.Paul@gmx.de wrote:

On 01/04/2016 08:00 PM, doug moen wrote:

Yes, it might need extensions, it's not just for Python though.
The Website claims: "...but C/C++ is already supported as well,
and it is planned to add special support for other languages as
well." so it might not be too complicated to have it handle
OpenSCAD as well.

But yes, it's just an example. If there's a different tool that
maybe just needs some configuration or so, that's perfect.

Cool, why not. I guess MarkDown is a good option. I don't like
that it's not going to be standardized, but it's wide adoption
still makes it a sensible choice.

ciao,
Torsten.

I know the Sphinx documentation claims C++ support, but this is done by
invoking Doxygen via Breathe. http://breathe.readthedocs.org/en/latest/

On 4 January 2016 at 14:19, Torsten Paul Torsten.Paul@gmx.de wrote: