Page MenuHomePhabricator

Generate C# reference API documentation
Open, HighPublic

Description

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.

cedric created this task.Oct 2 2017, 3:41 PM
ajwillia.ms lowered the priority of this task from High to Wishlist.Jan 4 2018, 7:48 AM
zmike edited projects, added Restricted Project; removed efl.Jun 11 2018, 6:57 AM
zmike edited projects, added efl: docs, efl: language bindings; removed Restricted Project.Jun 11 2018, 9:10 AM
q66 claimed this task.Jul 26 2018, 2:32 AM
q66 raised the priority of this task from Wishlist to Normal.
q66 added a subscriber: felipealmeida.

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.

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.

@lauromoura We already do that with src/scripts/elua generator for C#.

@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.

q66 added a comment.Oct 4 2018, 6:31 AM

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.

How's this coming along, @q66?

q66 added a comment.Nov 1 2018, 4:06 AM

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.

OK, I can work on the C# doc generator once the new infrastructure is in place!

q66 added a comment.Nov 2 2018, 7:20 AM

Perfect. We can synchronize efforts later then.

@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?

@segfaultxavi yeah. That's a problem. I think manually documenting it for the site would be necessary.

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.

segfaultxavi claimed this task.

DocFX is progressing fine. I think it is the easiest route.

segfaultxavi raised the priority of this task from Normal to High.Wed, Dec 5, 10:24 AM
q66 added a comment.Wed, Dec 5, 11:54 AM

Does this mean we will not need C# support inside the eo doc generator?

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.

q66 added a comment.Thu, Dec 6, 5:12 AM

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.