Summary:
Property docs, when present, should always be included in Property and Accessor
(setter and getter) docs.
Accessor docs, when present, should be included in their accessor method, and
also in the property method, as a side note.
This patch does just that.
Depends on D10285
Ref T8309
Test Plan: Generate docs and take a look at `Efl.Ui.Calendar`, for example, which has a bit of everything.
Reviewers: lauromoura
Reviewed By: lauromoura
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Maniphest Tasks: T8309
Differential Revision: https://phab.enlightenment.org/D10298
This was meant to happen but did not previously happen. It is not
ideal to do it now but better do it while we still can.
In short, this removes one half of the variables API (keeps
constants as they are) and repurposes the API to be only for
constants. This is also better for consistency to match errors.
Summary:
For better indentation, adding a blank line in the end of
methods.
Test Plan:
using efl_ui_layout.eo.cs, efl_access_object.eo.cs, efl_part.eo.cs and efl_ui_factory_bind.eo.cs as references,
apply changes to the code then check the diffs of after and before of the references files
Reviewers: lauromoura, felipealmeida
Reviewed By: lauromoura
Subscribers: cedric, felipealmeida, lauromoura
Tags: PHID-PROJ-uhnmnvlvunw6jgoqdnd4, #efl_language_bindings, #refactoring
Maniphest Tasks: T8167
Differential Revision: https://phab.enlightenment.org/D9712
Summary:
This also adds the information of default values in `parameter_def`.
This will help adding actual default parameter support in the C#
bindings.
Thanks to @segfaultxavi for improved formatting and escaping.
Fixes T8224
Reviewers: segfaultxavi, felipealmeida, brunobelo
Reviewed By: segfaultxavi
Subscribers: cedric, #reviewers, segfaultxavi, #committers
Tags: #efl
Maniphest Tasks: T8224
Differential Revision: https://phab.enlightenment.org/D10050
XML examples must provide their own <example> and <code> tags, and these
tags MUST be escaped: \< \> \" etc.
This is more inconvenient, but it allows adding explanatory text outside
the <code> and inside the <example>.
Examples are first looked for in XML format, and if not found, in CS format.
Summary:
Eolian allows non-public members in interfaces and mixins (usually
@protected). As both kinds are converted to C# interfaces, this
causes problem as non-public members are forbidden in C# interfaces.
This commit changes eolian_mono by removing those members from the C#
interfaces. If a generated class implements the interface, the method is
generated as if it were a protected member of the class directly.
For mixed properties like `Efl.Io.Reader.CanRead { get; set @protected; }`,
the interface has only the public getter and the the implementing class has both
the public getter and the protected setter.
With this, C# devs won't be able to directly implement protected Eo
methods from interfaces. (But this really does not make sense from the
C# point of view).
ref T7494
Reviewers: segfaultxavi, felipealmeida, YOhoho
Reviewed By: YOhoho
Subscribers: cedric, brunobelo, Jaehyun_Cho, #reviewers, woohyun, #committers
Tags: #efl
Maniphest Tasks: T7494
Differential Revision: https://phab.enlightenment.org/D9800
Summary:
Escapes a single string, without leading `///`
Depends on D9481
Reviewers: segfaultxavi, felipealmeida
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D9482
Summary:
Previous commit added a <remarks> section to BETA classes.
Methods (and properties) cannot have <remarks> section so a bit
of bold text is added instead to their summary.
Depends on D9380
Test Plan: Generate docs and observe beta methods and properties have a note regarding their betaness in the summary.
Reviewers: lauromoura, vitor.sousa
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D9382
Summary:
The mono generator adds a <remarks> section to all BETA classes with an explanatory text.
These tags are understood by DocFX and Monodevelop.
On top of this, this commit modifies the DocFX template to give the Remarks section a more
prominent place in the page.
Test Plan: Render docs, Beta classes should have a big blue box with a remark about the class being Beta and dangerous.
Reviewers: lauromoura, vitor.sousa
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D9381
Summary:
When skipping beta items, make sure generated documentation does not try
to refer to beta stuff using `see` tags. Doing so would lead to warnings
when generating the xml doc file and as we now treat warnings as errors,
compilation would fail.
Instead of `see` tags, use a simple `span` with a suffix text explaining
said item is beta.
Reviewers: vitor.sousa, felipealmeida, segfaultxavi
Reviewed By: segfaultxavi
Subscribers: cedric, #reviewers, #committers
Tags: #efl, #expertise_solutions
Differential Revision: https://phab.enlightenment.org/D9258
Summary:
After D8397, interfaces have the I prefix again, so the "Do" prefix on
methods with repeated names may not be needed for them in most cases.
This commit also consolidates the method_managed_name calls with the
overload receiving attributes::function_def instead of plain name.
Fixes T7791
Depends on D8645
Reviewers: vitor.sousa, felipealmeida, segfaultxavi
Reviewed By: segfaultxavi
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Maniphest Tasks: T7791
Differential Revision: https://phab.enlightenment.org/D8650
Summary: Also do not generated empty tag if doc would be empty.
Reviewers: vitor.sousa, segfaultxavi
Reviewed By: vitor.sousa, segfaultxavi
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8612
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.
Reviewers: lauromoura, vitor.sousa
Reviewed By: vitor.sousa
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8597
First code line was indented differently by DocFX because of tabs,
whitespace or who knows what. This adds a newline after the <code>
tag so all code lines have the same indentation.
Summary:
New option added to eolian_gen: -e <dir>
This specifies a directory to search for examples. If a file is found with the
same name as an EFL C# class (e.g. Efl.Ui.Button.cs) or as an EFL C# method or
property (e.g. Efl.IText.Text.cs, Efl.IText.SetText.cs) its full
contents will be embedded in the documentation for that class or method within
<example> and <code> tags. This is, in turn, is parsed by DocFX and shown
in Example boxes in the generated pages.
If an example file is not found, no examples are embedded for that object.
If -e is not used, no examples are embedded for any object.
New option added to meson: mono-examples-dir to point to the examples directory.
This directory is then passed to eolian_mono through -e.
Do not use it (or define it to nothing) to disable example embedding.
No performance drop has been observed because of these extra tests.
Right now examples can only be given for base classes, not for derived ones
(i.e. Efl.IText.Text but not Efl.Ui.Button.Text). This will be addressed in a
later commit.
Feature
Depends on D8587
Test Plan:
Create an examples folder and put some files in it:
```
mkdir /tmp/examples
echo 'var button = new Efl.Ui.Button();' > /tmp/examples/Efl.Ui.Button.cs
echo 'button.AutoRepeatEnabled = true;' > /tmp/examples/Efl.Ui.IAutorepeat.AutorepeatEnabled.cs
echo 'button.SetAutoRepeatEnabled(true);' > /tmp/examples/Efl.Ui.IAutorepeat.SetAutorepeatEnabled.cs
```
Configure meson to embed examples and build:
```
meson configure -Dmono-examples-dir=/tmp/examples
ninja
```
Examine the generated efl_ui_button.eo.cs file to see embedded <example> tags,
or run DocFX and bask in the glory of documentation pages with examples:
```
cd doc/docfx
./gendoc.sh
```
Reviewers: lauromoura, felipealmeida, vitor.sousa, zmike, bu5hm4n
Reviewed By: vitor.sousa
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8592
Summary:
This allows inserting nested tags like:
<example><code>bla bla bla</code></example>
The generate_tag_example() is currently unused but serves as an example.
Depends on D8585
Test Plan:
Not much, unless you want to manually call generate_tag_example()
(Which I have done, and it works, I promise).
Reviewers: lauromoura, vitor.sousa
Reviewed By: vitor.sousa
Subscribers: vitor.sousa, cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8587
Summary:
Methods without a class (global) make the previous code crash because
func.klass contains something (it cannot be NULL because it is a reference)
but you cannot make much calls on this something.
Test Plan: Currently there are no such references, but I need this working for upcoming patches.
Reviewers: lauromoura, vitor.sousa
Reviewed By: vitor.sousa
Subscribers: vitor.sousa, cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8585
Summary:
Conforming to C# coding conventions.
For properties, now we only generate a wrapper if its name does not
clash with the name of the class that would be implementing it.
Fixes T7751
Reviewers: vitor.sousa, felipealmeida, segfaultxavi
Reviewed By: vitor.sousa, segfaultxavi
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Maniphest Tasks: T7751
Differential Revision: https://phab.enlightenment.org/D8397
Summary:
Only the number was being used, and in places were it should not be.
Now the Since version appears only in <summary> tags, with proper
context (Since EFL 1.22).
Test Plan: make && gendoc should produce DocFX pages which make more sense.
Reviewers: lauromoura, zmike, bu5hm4n
Reviewed By: lauromoura
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8012
Summary:
This removes all Eolian API that deals with handling of legacy
code. It also removes the code using it in the generator as well
as bindings, but for now keeps generation of .eo.legacy.h types,
as there are still instances in our codebase where things are
otherwise broken. We can remove the rest once that is resolved.
Reviewers: zmike, cedric
Subscribers: #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8255
Summary:
Support for global constant variables has been recently added to the C# bindings.
This patch fixes doc references so they use the proper name.
This brings the mono doc warnings from 71 down to 29.
Depends on D8048
Test Plan:
Just build and see less doc warnings when building the C# bindings.
Also, doc refs to constants are links now.
Reviewers: lauromoura, vitor.sousa
Reviewed By: lauromoura
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8051
eolian_mono now generates properties (which simply wrap the setter and getter
methods when both ara available), but they were missing docs, because
properties require a special <value> tag instead of <returns> or <param> which
we are already implementing.
This commit adds <value> tags only if docs can be retrieved from the setter or
the getter methods.
Summary:
Some EO docs include () after a @method reference (some don't).
When the method reference is redered by DocFX it already includes
the trailing parenthese (and it even includes the parameter types),
so it looks very weird: Efl.Gfx.Stack.Raise()()
This patch removes the "()" string from any text comment following
an @ reference.
Test Plan:
Check DocFX docs for Efl.Gfx.Stack.Lower before and after this patch.
There are references to other methods which include the double parentheses.
Reviewers: lauromoura
Reviewed By: lauromoura
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D7504
Summary:
This allows them to be nicely rendered by IDEs and automatic
documentation generators like DocFX.
The conversion includes things like turning $name to <c>name</c>
or solving references to objects, which in turn requires converting
from EO object names to C# names.
It uses the same helper methods used to generate the C# object names,
so if these change in the future, the references in the comments
will change too.
Additionally, this patch fixes some minor bugs, like <para> tags
outside <summary> tags, misspelled <returns> tags or missing <returns>
documentation for getter methods.
Fixes T7453
Reviewers: lauromoura, vitor.sousa
Reviewed By: lauromoura
Subscribers: cedric, #reviewers, #committers
Tags: #efl
Maniphest Tasks: T7453
Differential Revision: https://phab.enlightenment.org/D7467
Summary:
Making it easier to share code between self and inherited events.
During this move, the namespace and keyword headers were merged into the
name_helpers header.
Also added the first seed of a generic namespace reducer function,
to be used by other functions in later commits.
Depends on D5994
Reviewers: felipealmeida
Reviewed By: felipealmeida
Subscribers: segfaultxavi, cedric
Differential Revision: https://phab.enlightenment.org/D5995
This commit adds the "documentation" generator, which gets the
documentation_def attribute of the given item and generates xml comments
to be exported by MCS.
For items requiring some customization of the generated comments (e.g.
functions and its parameters), the helpers to generate the preamble
(summary), body (paragraphs) and epilogue (currently just the @since
tag) were added.
Currently we do not support converting Eolian references into xmldoc
references.
As we explicitly generate Get/Set methods for properties, for now the
generator tries to get the get/set specific documentation first. If it
is not present, fallback to the common docs.
Later this could be changed to generate the common one as paragraphs of
the Get/Set.
Also some generated code like the wrappers for calling C# methods
from C can be private. This will cleanup the introspection results
and warnings when generating documentation.
Due to this visibility change, the binbuf tests had to be changed
to add redirect calls to the native methods instead of directly
calling the DllImport'd methods.