Page MenuHomePhabricator

mono-docs: Allow derived classes to have external examples
ClosedPublic

Authored by segfaultxavi on Apr 11 2019, 3:47 AM.

Details

Summary

You can now have external example files for derived classes (Efl.Ui.Button.SetText)
as well as for base classes (Efl.IText.SetText).
If both files are present, both examples are embedded in the docs. The more
examples the better!

Examples for classes in-between the hierarchy (Efl.Ui.Widget.SetText) are not
picked up. Might be worth examining in the future.

Test Plan

Create example files for both Efl.Ui.Button.AutorepeatEnabled.cs and Efl.Ui.IAutorepeat.AutorepeatEnabled.cs.
You should see both examples appearing in the docs.

Diff Detail

Repository
rEFL core/efl
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.
segfaultxavi created this revision.Apr 11 2019, 3:47 AM
segfaultxavi requested review of this revision.Apr 11 2019, 3:47 AM
vitor.sousa added inline comments.Apr 11 2019, 8:18 AM
src/bin/eolian_mono/eolian/mono/klass.hh
284–286

Shouldn't it be klass_full_concrete_or_interface_name?

vitor.sousa requested changes to this revision.Apr 11 2019, 8:22 AM
vitor.sousa added inline comments.
src/bin/eolian_mono/eolian/mono/documentation.hh
429

I dislike this style of code alignment, but sadly efl conventions demands it.
So, in this case I think context) should also be aligned with the rest of the parameters.

448

ditto

This revision now requires changes to proceed.Apr 11 2019, 8:22 AM

Fix examples appearing twice when a method is NOT inherited.

Whitespaaaaaaaaace

segfaultxavi marked 2 inline comments as done.Apr 11 2019, 8:30 AM
segfaultxavi added inline comments.
src/bin/eolian_mono/eolian/mono/documentation.hh
429

Yeah, missed these two :(

src/bin/eolian_mono/eolian/mono/klass.hh
284–286

To be honest, I am not sure. But we get here only for regular or abstract classes so the Concrete or I affixes shouldn't come into play.

I tested it, everything seems to be correct now.
But wouldn't it be easier to pass prop.klass/func.klass directly to generate_all_tag_examples than adding a new field to class_context?

I think if we go with the new field, we should at least fill this information in all places where this context is added.
And in respect to that, I took a look and klass_full_interface_name really has a different code logic than klass_full_concrete_or_interface_name but the end result is always the same...
But I think in this case klass_full_concrete_or_interface_name would better express the desired class.

What do you think?

segfaultxavi planned changes to this revision.Apr 11 2019, 12:51 PM
segfaultxavi marked an inline comment as done.

But wouldn't it be easier to pass prop.klass/func.klass directly to generate_all_tag_examples than adding a new field to class_context?

That's the thing! When parsing Efl.Ui.Button.GetText(), func.klass is Efl.IText, this is, the class where this method is defined. This is the current behavior (before this patch).
But if I want to allow specific examples for every derived class I need the class currently being processed, and it seems it is not available when we are generating the documentation (or at least, I could not find it). @lauromoura
suggested adding a context tag.
Beside the derived class examples (Efl.Ui.Button) I also look at the base class (Efl.IText) in case there is an example there too.

I think if we go with the new field, we should at least fill this information in all places where this context is added.

sigh, yes, you are right, I tried to play fast and loose here. Will fix.

And in respect to that, I took a look and klass_full_interface_name really has a different code logic than klass_full_concrete_or_interface_name but the end result is always the same...
But I think in this case klass_full_concrete_or_interface_name would better express the desired class.

Every time I need the managed name for something I spend 1h browsing name_helpers trying to figure out which one should I use :)
I'll trust your expertise and use that method!

But wouldn't it be easier to pass prop.klass/func.klass directly to generate_all_tag_examples than adding a new field to class_context?

That's the thing! When parsing Efl.Ui.Button.GetText(), func.klass is Efl.IText, this is, the class where this method is defined. This is the current behavior (before this patch).

Oh, right! Great, so a new context field, that is it =)

Always set class name when creating class_context structs.
Use klass_full_concrete_or_interface_name to obtain class names.

I know the indentation is not correct (I'm mixing ( and {) but can we let it slip? otherwise the line will be very long and I do not think it helps readability in any way :)

vitor.sousa accepted this revision.Apr 12 2019, 8:51 AM

Awesome

This revision is now accepted and ready to land.Apr 12 2019, 8:51 AM
This revision was automatically updated to reflect the committed changes.