search

gtk-rs / gir

Tool to generate rust bindings and user API for glib-based libraries
https://gtk-rs.org/gir/book/
MIT License
238 stars 107 forks source link

Docs don't shows that class implements manual traits #683

Open EPashkin opened 5 years ago

EPashkin commented 5 years ago

We have Implements section in docs, in which listed all "Ext" traits for object and it parents. The problem is that some objects also has manual or signal traits that are not listed here.

I see at minimum 2 possible solutions:

cc @GuillaumeGomez, @sdroege

GuillaumeGomez commented 5 years ago

Ah indeed. Good catch!

Le mer. 26 déc. 2018 à 20:17, Evgenii Pashkin notifications@github.com a écrit :

We have Implements section in docs, in which listed all "Ext" traits for object and it parents. The problem is that some objects also has manual or signal traits that are not listed here.

I see at minimum 2 possible solutions:

  1. Add config "manual_trait" (or "manual_traits" if some object have many) with name of manual trait.
  2. Remove manual traits completely, Ex. by allow define its functions as "snippet" in separate file that will be inserted to generated file in right place.

cc @GuillaumeGomez https://github.com/GuillaumeGomez, @sdroege https://github.com/sdroege

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/gtk-rs/gir/issues/683, or mute the thread https://github.com/notifications/unsubscribe-auth/AC6KTMeGHWk_-iqsslEPzOxffiWEBPyMks5u88tHgaJpZM4ZiBTN .

sdroege commented 5 years ago

I like 2., but there are also cases where you still need 1. E.g. if you want to have something like a FooUnixExt trait.

EPashkin commented 5 years ago

FooUnixExt trait can't be just functions with right cfgs in FooExt ?

sdroege commented 5 years ago

FooUnixExt trait can't be just functions with right cfgs in FooExt ?

Yes, but if it's multiple similar functions then it's nicer to have it all bundled in a single trait. See also the extension traits in the std library for similar purposes.

EPashkin commented 5 years ago

About templates: from beginning I thought that we need insert templates to 4 places:

Problem how to store template: 1) in one file per class (some_class.template.rs) separated by some comments (Ex. "////Begin trait", "///Begin impl trait" etc.) 2) many files per class (some_class.trait.rs, some_class.impl_trait.rs) 3) Single file with comments, this is IMHO worst case.

Now I think that we need only "trait" and "impl trait" as other 2 can be written as now in separate file (/src/some_class.rs) without templates.

@sdroege, @GuillaumeGomez what you think about this?

@sdroege You did mean something like this for subclass code generation in https://github.com/gtk-rs/gtk/issues/765#issuecomment-457634712?

EPashkin commented 5 years ago

@GuillaumeGomez, as @sdroege mentioned "if it's multiple similar functions then it's nicer to have it all bundled in a single trait" seems we need do both cases. We can do code analyze and update "Implements" in "gir doc", but IMHO this will have same problem as config "manual_trait" for counting parent manual implementation.

GuillaumeGomez commented 5 years ago

I still wonder how we can know for sure that we implement it manually though...

sdroege commented 5 years ago

@EPashkin I like the second option, yes. For subclassing we need to add 2 (IIRC) more template files per class.

EPashkin commented 5 years ago

Strange thing in doc generation, that I don't understand and can't solve.

All manual traits documented only in prelude module, while normal traits documented both in crate and crate::prelude: https://gtk-rs.org/docs/gio/prelude/trait.ApplicationExtManual.html va https://gtk-rs.org/docs/gio/trait.ApplicationExt.html + https://gtk-rs.org/docs/gio/prelude/trait.ApplicationExt.html

EPashkin commented 5 years ago

Same problem with AppChooserExt link in https://gtk-rs.org/docs/gtk/struct.AppChooser.html: it present only in prelude https://gtk-rs.org/docs/gtk/prelude/trait.AppChooserExt.html

EPashkin commented 5 years ago

All linked PR updated https://github.com/gtk-rs/gio/pull/184 and https://github.com/gtk-rs/gtk/pull/766 ready for merge Second commit of https://github.com/gtk-rs/lgpl-docs/pull/48 ready for checking results, I will add 3th commit later when I done with Ubunto Disco gir-files.

EPashkin commented 5 years ago

Only manual trait that not added to docs is gtk::DragContextExtManual, because it can be only added to gdk, and I don't sure that it right.