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.
Xavi Artigas
Lauro Moura
Daniel Kolesa
Felipe Magno de Almeida