parser: Add doc format support #1641
Conversation
Replaces the current use_gi_docgen key
|
Obviously this was untested, so please don't merge. |
| @@ -138,7 +140,7 @@ fn replace_symbols( | |||
| env: &Env, | |||
| in_type: Option<(&TypeId, Option<LocationInObject>)>, | |||
| ) -> String { | |||
| if env.config.use_gi_docgen { | |||
| if env.library.doc_format == DocFormat::GiDocgen { | |||
There was a problem hiding this comment.
Perhaps for now this could be a if library.doc_format == DocFormat::GiDocgen || config.use_gi_docgen for the moment.
There was a problem hiding this comment.
that is an option yes, although, it will end up staying there given no one will remember to remove it. As this option only impacts docs generation, i rather have bindings manually amend the format into the gir file then gir keeping this old "hack"
There was a problem hiding this comment.
My fear is that this is a bit of a chicken and egg situation. Breaking gir generation is a discouragement for setting doc_format and this MR depends on libraries using it.
I suppose an alternative is to have a prequel for this PR that just reads the doc_format and does nothing with it (instead of crashing) to unblock the situation, such a MR would not depend on gir-files.
There was a problem hiding this comment.
It is always been like that when it comes to new annotations so i rather fix things properly.
|
Please link https://gitlab.gnome.org/GNOME/gobject-introspection/-/merge_requests/401 in the commit message. |
| @@ -336,7 +335,7 @@ status = "generate" | |||
| name = "stock_list_ids" | |||
| # allows to ignore global functions | |||
| ignore = true | |||
| # allows to define if the function was moved to a trait | |||
| # allows to define if the function was moved to a trait | |||
There was a problem hiding this comment.
These could go in a separate commit.
| GtkDocMarkdown, | ||
| GtkDocDocbook, | ||
| GiDocgen, | ||
| HotDoc, |
There was a problem hiding this comment.
This should be Hotdoc if the key is not hot-doc.
| @@ -14,7 +14,6 @@ target_path = "." | |||
| # auto_path = "src/auto" | |||
| work_mode = "normal" | |||
| # Whether the library uses https://gitlab.gnome.org/GNOME/gi-docgen for its documentation | |||
| use_gi_docgen = false | |||
There was a problem hiding this comment.
It's going to take a while until everything uses this so for the time being maybe change use_gi_docgen to doc_format and allow the same values there, and don't make the attribute in the XML mandatory yet?
There was a problem hiding this comment.
What is everything? It is GTK, GLib, Pango and libadwaita (merged already https://gitlab.gnome.org/GNOME/libadwaita/-/merge_requests/1428).
The remaining bindings don't get updated often at all.
If you just want to ignore the element for now, it could be done in a separate patch by someone else.
There was a problem hiding this comment.
If everything using gi-docgen is updated then that's fine with me. Just default to "unknown" if the attribute is not in the XML.
|
I built gir 0.20.5 with this MR added as patch; though I still get the Unexpected element " error. |
|
Did the changes to ignore the attribute in #1645, other changes could be done separately later to not block other packages forever & we can backport it easily. |
Replaces the current use_gi_docgen key
We would need gtk-rs/gir-files#237 to land first but that is blocked on more core libraries defining the doc:format properly.