Documentation Tracking Issue & Recommendations
pragmatrix opened this issue · comments
This is the tracking issue that covers the documentation attempt of skia-safe.
And these are my suggestions on how to add documentation:
Update: With #679, we've added document-converter project in the repository that aids in converting Skia C++ Doxygen comments to Rust. It's a simple filter executable that converts C++ Skia comments from stdin to Rust comments on stdout. If you are using Visual Studio Code, the extension FilterText can be used to convert the current selection.
- Documentation should be copied from the original Skia documentation and modified sparsely to match the expectations of a Rust developer:
- Rename function parameter names and enclose them with backticks.
- Fix references to types. Removing the
Skprefix and enclosing them in[]is usually sufficient. - Reformat the comments to a width of 100. I recommend the VSCode Extension Rewrap for doing that.
- Run
cargo docto see the warnings.
- Additional code examples may be added.
- Documentation of yet undocumented Skia types and functions may be added.
While I do appreciate more detailed documentation, I fear that this leads up into a long term maintenance issue. Skia updates are coming in fast and they almost always break the public API surface. I see my job in keeping skia-safe up to date with Skia while maintaining backward compatibility whenever possible, but this is getting harder if skia-safe diverges too much from the original Skia APIs, which in turn affects documentation more than code, because outdated documentation does not cause compilation errors.
If you'd like to help, base the documentation on the next Milestone PR and the Skia branch it is referring to as a submodule. If there is no current Milestone PR open, you can base your documentation PR on the master branch.
Documented:
-
core/-
canvas.rs- 0.40 -
bitmap.rs- 0.38 -
image.rs- 0.54 -
path.rs- 0.54 -
surface- 0.61 -
yuva_info.rs- 0.37 -
yuva_pixmaps.rs- 0.37
-
- textlayout / skparagraph module - #793, 0.61
/cc @Vurich
Sorry I think I fundamentally disagree with you about how this should be done.
I think that you should take a step back and consider allowing me to use a static analyzer to write pretty much all the documentation.
It will analyze your functions that convert the C++ API's into C. Above those functions it will just put a list of absolute paths to different Skia functions that are used in the execution of this function (e.g. SkPath::addPath).
Then onto Rust. Every time you call a C function, we will include links to the Skia docs for the underlying C++ APIs that are getting used. We can even provide a code sample that would just be the function body of the C function. Or if you want to keep it simple we won't.
In Rust we can, if the case is unambiguous, that is to say, this Rust function only calls at most one C function, which in turn only calls one C++ function from the Skia library, take the description in C++ and copy it word for word to Rust.
There are likely to be scenarios where that fails. For example you may need to call multiple C functions from Rust. But if that is the case I think perhaps even in obvious cases where you are just doing it to manage memory we probably should note the difference between what Rust does and what C++ does for a similarly named function.
Basically to summarize my last post I think that your ideal solution is way too magical. It will break constantly as things change. My solution meanwhile, although it likely will not result in as much of a wow factor, will keep working regardless of what happens to either your binding or the underlying code. So my solution is much less frustrating to have to maintain.
I would also say that given we have gone more than 2 years without this being solved your way perhaps allowing me to try it my way is not so bad, and then if you want to replace my way with a very magical way that would try to close the gap between Rust and C++ via code formatting and regexps you can do that.
I appreciate very much that you want to move the documentation forward.
And if you are able to do that like you suggested, I am happy to follow along that path. But I am not sure if static analysis is even needed given that a simple link to the C++ documentation would serve most purposes (pointing to the online reference perhaps?).
Initially, I planned to just copy the bindgen extracted C++ documentation, or link to it, but then decided to disable the documentation extraction and not copy C++ documentation verbatim to Rust, because I feared it would be too confusing, e.g. all the identifiers and types are different, and it also caused some problems confusing the Rust documentation parser.
... way too magical ...
I would consider using a static analyzer for creating documentation more magical than manually converting documentation and updating it with a clearly defined process. The term "magical" is something that is relative to one's perspective and knowledge.
It will break constantly as things change.
Recent and past Skia updates did not cause significant changes in terms of documentation and public API surface. The process I've layouted also integrates fine with the milestone updating process which requires to take a look at the milestone diffs of all header files anyways.
@pragmatrix that is on me, clearly I did not understand your intention, I thought you were already recommending a static analyzer to go through and try to do all of that reordering without it being done manually. I didn't understand that your proposed solution was manual, (because it seems like too much work to me 😂).
But then again you put a phenomenal amount of work into this project, thank you!
I would find having documentation very helpful so I will see how far I get with my idea...