Consider inserting C++ declarations as comments

[fpq473]

Thanks for this awesome project.

I am trying to code-generate a Python wrapper around opencascade.js for pyodide, and hoping to handle default values and references. I see this debated in other issues and discussions, and see their resolution as a medium-term goal.

I was hoping for a stop-gap half-measure, which could be fairly easy to implement and also be generally helpful: write the C++ function declaration as a comment in the typescript declaration file. For example:

export declare class TopExp_Explorer {
  // void Init (const TopoDS_Shape &S, const TopAbs_ShapeEnum ToFind, const TopAbs_ShapeEnum ToAvoid=TopAbs_SHAPE)
  Init(S: TopoDS_Shape, ToFind: TopAbs_ShapeEnum, ToAvoid: TopAbs_ShapeEnum): void;

and

export declare class Bnd_Box {
  // void Get (Standard_Real &theXmin, Standard_Real &theYmin, Standard_Real &theZmin, Standard_Real &theXmax, Standard_Real &theYmax, Standard_Real &theZmax) const
  Get(theXmin: Standard_Real, theYmin: Standard_Real, theZmin: Standard_Real, theXmax: Standard_Real, theYmax: Standard_Real, theZmax: Standard_Real): void;

This seems within reach because IIUC the C++ function declarations must have been parsed at some point in the pipeline, and the declaration just needs to be kept and written out. I tried to do this myself but couldn't figure it out -- thought Bindings.processMethodOrProperty() had that information.

These comments would allow more functional Python wrappers around TopExp_Explorer.Init() and Bnd_Box.Get() to be generated.

[donalffons]

Hey, interesting project! Are you aware of pyOCCT and python-occ (the latter might now be unmaintained, I believe)?! Wouldn't those be easier solutions for what you want to achieve?

References as function arguments work for built-in types, like integers and floats (see here). References (and pointers) to objects should also work fine, I believe.

References as return values are only partly working and need some re-engineering (and probably a breaking change, see #125).

Default values would be really nice to have. However, Emscripten's Embind doesn't have a built-in way to handle that. Instead, we would have to create one overload for every default argument a function has. This would probably also have negative impacts on runtime performance and file size. Together with the increase in complexity, these thing have held me back from implementing that yet.

[...] write the C++ function declaration as a comment in the typescript declaration file [...] thought Bindings.processMethodOrProperty() had that information.

I agree that having the C++ declaration would be helpful. It would also be easy to add the comment for the particular method (or class, property, ...) to the typescript definitions. These would have to be added to TypescriptBindings::processMethodOrProperty in bindings.py: method.type.spelling would give you the full type, like in your examples. method.brief_comment gives the related comment. If we start adding comments, we should use tsdoc - style comments.

These comments would allow more functional Python wrappers around TopExp_Explorer.Init() and Bnd_Box.Get() to be generated.

Just to avoid misunderstandings - You are not planning to use comments in the .d.ts file as an input for code / binding generation, are you?! I feel that would likely be very fragile. Instead, I would recommend to look at libclang, which this project uses to analyze the original OCCT source code.

[fpq473]

Thanks for the very helpful response. With your hints I was able to write out the extra information in a new key/value in the .d.ts.json file instead of as comments. I ended up using method.get_arguments()[i].get_tokens() to get the default values, as they were not in method.type.spelling.

I'm all set now, nothing else needed. (My confusion before opening this issue came from not deleting .d.ts.json files which caused all my attempts to appear not to work.)

As for the approach, I am targeting pyodide, a port of CPython to WebAssembly/Emscripten. My understanding is then that pyOCCT and python-occ are not applicable, and only this project is... is that right?

[donalffons]

Sounds good.

I am targeting pyodide, a port of CPython to WebAssembly/Emscripten. My understanding is then that pyOCCT and python-occ are not applicable, and only this project is... is that right?

Not sure - I'm not familiar with pyodide...