The goal is to enable the docuwiki to contain proper documentation for all API generated from .eo with specific insight on C#. This will be a first binding to integrate information in the reference API documentation.
Description
Description
| Status | Assigned | Task | ||
|---|---|---|---|---|
| Open | None | T5826 Improve overall EFL documentation | ||
| Open | None | T6127 Provide documentation for C# | ||
| Open | segfaultxavi | T6128 Generate C# reference API documentation | ||
| Resolved | segfaultxavi | T7424 Add support for DocFx to generate the C# API docs | ||
| Resolved | zmike | T7527 Support DocFX from meson | ||
| Resolved | lauromoura | T7451 efl-mono: Only expose API methods relevant to the user | ||
| Resolved | segfaultxavi | T7453 C# bindings: Convert Eo comment format into proper XML comment format | ||
| Resolved | segfaultxavi | T7482 eo docs: Remove Doxygen tags from efl*.eo files | ||
| Open | lauromoura | T7505 efl-mono: Add <value> tags to Properties documentation | ||
| Open | felipealmeida | T7519 C#: Hide DllImport'd methods into a NativeMethods subclass |
Comment Actions
As talked over previously, I will claim this task and integrate C# into the current documentation generator. Before that, I intend to rewrite the documentation generator using a simpler design, so that it will become easier to integrate C# and other languages into it.
Comment Actions
The Mono compiler already extracts the documentation from the generated code (eolian_mono adds them as C# comments) into a XML file that VS/MonoDevelop use. Maybe we could just add a script to transform the generated XML into the DokuWiki syntax.
This has the advantage of automatically generating docs for the manual binding code too.
Comment Actions
@lauromoura Kolesa will probably rewrite the generator, we can then later fix anything that comes by. This has the advantage that the C generator will already generate DokuWiki-syntax and do whatever beautification that may be needed.
Comment Actions
The generator rewrite is pretty much done btw, including refactored C# support. It will be announced and hopefully made into an official repository within a few days.
Comment Actions
I took a break from that to work on meson, eolian_aux (which will be used to move some of the core from the docgen) and some other things, but the code is all in my personal dev repo... I will try to get a proper repository set up early next week or maybe even during this weekend. If somebody wants to help with working on the doc generator or even provide feedback on the generated output, go ahead, it would be much appreciated.
Comment Actions
@felipealmeida If we generate the C# API docs directly from the EO files, how can we document the methods that are manually defined in the bindings (the ones @lauromoura was referring to)?
I guess things like the constructors with multiple parameters (enabled by the new @ctor_param tag) are going to be difficult to generate directly from EO. Do you have any suggestion?
Comment Actions
@segfaultxavi yeah. That's a problem. I think manually documenting it for the site would be necessary.
Comment Actions
I am spending some time studying DocFx (T7424) to go along the alternate route, that is, generate the site docs from the xml output of eolian_mono. I'll let everybody know how that turns out.
Comment Actions
DocFX seems to be working now (in a branch), but it is a heavy dependency and it takes ages to generate the docs.
In the long run, I think it would be nicer to have our own generator, but, for now, let's just lower the priority of it and use DocFX once it is finished.
Comment Actions
Well, since it covers all the C# docs, I'll just go ahead and remove it from our own generator for the time being. The current C# code is pretty much copy-paste-parts-of-the-generator-into-separate-file-and-modify and it's kind of a pain to do changes in it as i make them in the rest of the generator, so if we want C# support later in it, might as well just write it from scratch.