Verbatim comments translation for C# #1695

wkalinin · 2020-01-04T16:17:20Z

Added literal doxygen comments translation for C#, which is enough for our needs. Hope other C# users would find that useful.

vadz

Thanks, I don't know how well is it going to work in practice, but it's definitely better than nothing. Out of curiosity, do you know what would the full implementation do, i.e. what should be translated to what?

It would be nice to enable at least the basic Doxygen tests (not using translation) for C#, having them pass would help to ensure that this doesn't get broken in the future.

vadz · 2020-01-05T23:36:39Z

Source/Modules/csharp.cxx

@@ -155,6 +161,7 @@ class CSHARP:public Language {
      director_method_types(NULL),
      director_connect_parms(NULL),
      destructor_call(NULL),
+      structuralComments(NULL),


This results in

Source/Modules/csharp.cxx:164:7: warning: field 'structuralComments' will be initialized after field 'output_file' [-Wreorder]

which is harmless here but still would be better to fix.

vadz · 2020-01-05T23:37:25Z

Source/Modules/csharp.cxx

@@ -46,6 +47,8 @@ class CSHARP:public Language {
  bool global_variable_flag;	// Flag for when wrapping a global variable
  bool old_variable_names;	// Flag for old style variable names in the intermediary class
  bool generate_property_declaration_flag;	// Flag for generating properties
+  bool doxygen;			//flag enabling comment processing
+  bool comment_creation_chatter; //flag for getting information about where comments were created


Was this supposed to be left in? Because there doesn't seem to be any way to set it, so it doesn't look useful in its current form.

Maybe set from the debugger (just like in Java module)

vadz · 2020-01-05T23:38:41Z

Source/Modules/csharp.cxx

@@ -1434,6 +1514,22 @@ class CSHARP:public Language {
    return SWIG_OK;
  }

+  /* -----------------------------------------------------------------------
+ * doxygenComment()
+ * Simply translates the doxygen comment and places it into the appropriate


I'm not sure if "translates" here is really correct, as it doesn't seem to be doing any translation, does it?

It depends on the translator, just default being verbatim copy. I mean, technically C# module knows that the translator is doing nothing only in module constructor (that may change if someone will introduce an alternative).

vadz · 2020-01-05T23:39:11Z

Source/Modules/csharp.cxx

@@ -1456,6 +1552,15 @@ class CSHARP:public Language {
    Swig_save("constantWrapper", n, "value", NIL);
    Swig_save("constantWrapper", n, "tmap:ctype:out", "tmap:imtype:out", "tmap:cstype:out", "tmap:out:null", "tmap:imtype:outattributes", "tmap:cstype:outattributes", NIL);

+    //translate and write comment if flagged


Sorry, could you please explain what do you mean by "if flagged" here?

Blind copy from the Java module, probably means "if enabled", removed now.

wkalinin · 2020-01-06T16:26:01Z

This is actually very old code, added when doxygen was just released in it's own branch. I'll fix the warning and remove the useless comments
I have no idea what comments may be translated to, our documentation tool supports Doxygen in C# just fine, so I needed to only copy the comments.
There are quite a bit of doxygen tests in Java test suite, what test would you recommend as essential?
(Sorry for the spam, did not relogin into real account)

minor formatting

ojwb · 2022-03-10T21:53:04Z

I think it would be best to have all the doxygen testcases for each supported language.

While there are quite a few, it looks like most of the hard work for a new language is implementing something equivalent to CommentParser which gets hold of the output doxygen comments, normalises it, and compares with the expected version.

The rest is an essentially mechanical conversion of the testcases, and the bulk of that could be scripted.

emmenlau · 2022-09-09T20:53:23Z

Doxygen support for C# would be great to have, so just kindly bumping this up again...

wsfulton · 2022-09-09T21:07:16Z

Converting and adding the Java doxygen tests for this C# doxygen support is what is required for this to be included into SWIG. The testcases that need converting from Java to C# are:

$ ls Examples/test-suite/java/doxygen_*runme.java
Examples/test-suite/java/doxygen_alias_runme.java
Examples/test-suite/java/doxygen_basic_notranslate_runme.java
Examples/test-suite/java/doxygen_basic_translate_runme.java
Examples/test-suite/java/doxygen_basic_translate_style2_runme.java
Examples/test-suite/java/doxygen_basic_translate_style3_runme.java
Examples/test-suite/java/doxygen_code_blocks_runme.java
Examples/test-suite/java/doxygen_ignore_runme.java
Examples/test-suite/java/doxygen_misc_constructs_runme.java
Examples/test-suite/java/doxygen_nested_class_runme.java
Examples/test-suite/java/doxygen_parsing_enums_proper_runme.java
Examples/test-suite/java/doxygen_parsing_enums_simple_runme.java
Examples/test-suite/java/doxygen_parsing_enums_typesafe_runme.java
Examples/test-suite/java/doxygen_parsing_enums_typeunsafe_runme.java
Examples/test-suite/java/doxygen_parsing_runme.java
Examples/test-suite/java/doxygen_translate_all_tags_runme.java
Examples/test-suite/java/doxygen_translate_links_runme.java
Examples/test-suite/java/doxygen_translate_runme.java

Converting Java code to C# code is normally quite easy.

emmenlau · 2022-09-10T06:39:49Z

@wkalinin you have already done a lot for C# doxygen support! Would you be willing to push this further? I don't feel confident that I'm ready to start here, but doxygen support would be really nice to have in master...

emmenlau · 2022-10-30T10:59:43Z

Dear @wkalinin, based on your nice work in this PR, I have continued with C# documentation support in #2421. My PR adds a few extensions on top of yours. I left your author name etc intact, and hope your appreciate my continued work.

Please let me know if this is in your best interest? Then we can possibly close one of the two merge requests and continue the collaborative effort in the remaining merge request. Your input and help is appreciated!

ojwb · 2023-05-08T04:09:44Z

Closing in favour of #2421.

Verbatim comments translation for C#

418f9b7

vadz reviewed Jan 5, 2020

View reviewed changes

vadz added C# Doxygen Related to -doxygen command line option labels Jan 5, 2020

warning fixed, meaningless comments removed

3c9fe78

fixed member comments generation (rebase error)

f008fc2

minor formatting

emmenlau mentioned this pull request Oct 30, 2022

Doxygen comments conversion for C# (CSharp, .Net, Managed) #2421

Open

ojwb closed this May 8, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Verbatim comments translation for C# #1695

Verbatim comments translation for C# #1695

wkalinin commented Jan 4, 2020

vadz left a comment

vadz Jan 5, 2020

vadz Jan 5, 2020

wkalinin Jan 6, 2020

vadz Jan 5, 2020

wkalinin Jan 6, 2020

vadz Jan 5, 2020

wkalinin Jan 6, 2020

wkalinin commented Jan 6, 2020

ojwb commented Mar 10, 2022

emmenlau commented Sep 9, 2022

wsfulton commented Sep 9, 2022

emmenlau commented Sep 10, 2022

emmenlau commented Oct 30, 2022

ojwb commented May 8, 2023

Verbatim comments translation for C# #1695

Verbatim comments translation for C# #1695

Conversation

wkalinin commented Jan 4, 2020

vadz left a comment

Choose a reason for hiding this comment

vadz Jan 5, 2020

Choose a reason for hiding this comment

vadz Jan 5, 2020

Choose a reason for hiding this comment

wkalinin Jan 6, 2020

Choose a reason for hiding this comment

vadz Jan 5, 2020

Choose a reason for hiding this comment

wkalinin Jan 6, 2020

Choose a reason for hiding this comment

vadz Jan 5, 2020

Choose a reason for hiding this comment

wkalinin Jan 6, 2020

Choose a reason for hiding this comment

wkalinin commented Jan 6, 2020

ojwb commented Mar 10, 2022

emmenlau commented Sep 9, 2022

wsfulton commented Sep 9, 2022

emmenlau commented Sep 10, 2022

emmenlau commented Oct 30, 2022

ojwb commented May 8, 2023