Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Verbatim comments translation for C# #1695

Closed
wants to merge 3 commits into from
Closed

Verbatim comments translation for C# #1695

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
418f9b7
Verbatim comments translation for C#
wkalinin Jan 4, 2020
3c9fe78
warning fixed, meaningless comments removed
wkalinin Jan 6, 2020
f008fc2
fixed member comments generation (rebase error)
wkalinin Jan 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Source/Doxygen/doxytranslator.cxx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,3 +67,9 @@ void DoxygenTranslator::printTree(const DoxygenEntityList &entityList) {
p->printEntity(0);
}
}

String* DoxygenTranslator::makeDocumentation(Node* node) {
if (String* documentation = getDoxygenComment(node))
return NewString(documentation);
return NewStringEmpty();
}
2 changes: 1 addition & 1 deletion Source/Doxygen/doxytranslator.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ class DoxygenTranslator {
/*
* Returns the documentation formatted for a target language.
*/
virtual String *makeDocumentation(Node *node) = 0;
virtual String *makeDocumentation(Node *node);

/*
* Prints the details of a parsed entity list to stdout (for debugging).
Expand Down
153 changes: 149 additions & 4 deletions Source/Modules/csharp.cxx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
#include <limits.h> // for INT_MAX
#include "cparse.h"
#include <ctype.h>
#include "../Doxygen/doxytranslator.h"

/* Hash type used for upcalls from C/C++ */
typedef DOH UpcallData;
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


String *imclass_name; // intermediary class name
String *module_class_name; // module class name
Expand Down Expand Up @@ -81,6 +84,7 @@ class CSHARP:public Language {
String *director_connect_parms; // Director delegates parameter list for director connect call
String *destructor_call; //C++ destructor call if any
String *output_file; // File name for single file mode. If set all generated code will be written to this file
String* structuralComments;

// Director method stuff:
List *dmethods_seq;
Expand Down Expand Up @@ -122,6 +126,8 @@ class CSHARP:public Language {
global_variable_flag(false),
old_variable_names(false),
generate_property_declaration_flag(false),
doxygen(false),
comment_creation_chatter(false),
imclass_name(NULL),
module_class_name(NULL),
imclass_class_code(NULL),
Expand Down Expand Up @@ -155,6 +161,7 @@ class CSHARP:public Language {
director_method_types(NULL),
director_connect_parms(NULL),
destructor_call(NULL),
structuralComments(NULL),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

output_file(NULL),
dmethods_seq(NULL),
dmethods_table(NULL),
Expand All @@ -169,6 +176,10 @@ class CSHARP:public Language {
director_language = 1;
}

~CSHARP() {
delete doxygenTranslator;
}

/* -----------------------------------------------------------------------------
* getProxyName()
*
Expand Down Expand Up @@ -221,6 +232,8 @@ class CSHARP:public Language {

SWIG_library_directory("csharp");

int doxygen_translator_flags = 0;

// Look for certain command line options
for (int i = 1; i < argc; i++) {
if (argv[i]) {
Expand Down Expand Up @@ -248,7 +261,21 @@ class CSHARP:public Language {
} else {
Swig_arg_error();
}
} else if ((strcmp(argv[i], "-noproxy") == 0)) {
}
else if ((strcmp(argv[i], "-doxygen") == 0)) {
Swig_mark_arg(i);
doxygen = true;
scan_doxygen_comments = true;
}
else if ((strcmp(argv[i], "-debug-doxygen-translator") == 0)) {
Swig_mark_arg(i);
doxygen_translator_flags |= DoxygenTranslator::debug_translator;
}
else if ((strcmp(argv[i], "-debug-doxygen-parser") == 0)) {
Swig_mark_arg(i);
doxygen_translator_flags |= DoxygenTranslator::debug_parser;
}
else if ((strcmp(argv[i], "-noproxy") == 0)) {
Swig_mark_arg(i);
proxy_flag = false;
} else if (strcmp(argv[i], "-oldvarnames") == 0) {
Expand All @@ -270,6 +297,9 @@ class CSHARP:public Language {
}
}

if (doxygen)
doxygenTranslator = new DoxygenTranslator(doxygen_translator_flags);

// Add a symbol to the parser for conditional compilation
Preprocessor_define("SWIGCSHARP 1", 0);

Expand Down Expand Up @@ -453,11 +483,23 @@ class CSHARP:public Language {
{
File *f_im = getOutputFile(SWIG_output_directory(), imclass_name);

//Add any structural comments to the top
if (doxygen && structuralComments)
Printf(f_im, "%s", structuralComments);

addOpenNamespace(0, f_im);

if (imclass_imports)
Printf(f_im, "%s\n", imclass_imports);

if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, 0);
if (comment_creation_chatter)
Printf(f_im, "/* This was generated from top() */");
Printv(f_im, " /** ", Char(doxygen_comments), " */\n", NIL);
Delete(doxygen_comments);
}

if (Len(imclass_class_modifiers) > 0)
Printf(f_im, "%s ", imclass_class_modifiers);
Printf(f_im, "%s ", imclass_name);
Expand Down Expand Up @@ -592,6 +634,8 @@ class CSHARP:public Language {
module_class_modifiers = NULL;
Delete(imclass_imports);
imclass_imports = NULL;
Delete(structuralComments);
structuralComments = NULL;
Delete(imclass_cppcasts_code);
imclass_cppcasts_code = NULL;
Delete(upcasts_code);
Expand Down Expand Up @@ -1201,6 +1245,15 @@ class CSHARP:public Language {
EnumFeature enum_feature = decodeEnumFeature(n);
String *typemap_lookup_type = Getattr(n, "name");

if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, 0);
if (comment_creation_chatter) {
Printf(enum_code, "/* This was generated from enumDeclaration() */");
}
Printv(enum_code, "/** ", Char(doxygen_comments), " */\n", NIL);
Delete(doxygen_comments);
}

if ((enum_feature != SimpleEnum) && symname && typemap_lookup_type) {
// Wrap (non-anonymous) C/C++ enum within a typesafe, typeunsafe or proper C# enum

Expand All @@ -1226,6 +1279,15 @@ class CSHARP:public Language {
// Wrap C++ enum with integers - just indicate start of enum with a comment, no comment for anonymous enums of any sort
if (symname && !Getattr(n, "unnamedinstance"))
Printf(constants_code, " // %s \n", symname);
// Translate and write javadoc comment for the enum itself if flagged
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, " ");
if (comment_creation_chatter)
Printf(constants_code, "/* This was generated from enumDeclaration() */\n");
Printf(constants_code, Char(doxygen_comments));
Printf(constants_code, "\n");
Delete(doxygen_comments);
}
}

// Emit each enum item
Expand Down Expand Up @@ -1367,7 +1429,16 @@ class CSHARP:public Language {
if (!GetFlag(n, "firstenumitem"))
Printf(enum_code, ",\n");

if (csattributes)
//translate and write comment if flagged
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, " ");
if (comment_creation_chatter)
Printf(enum_code, "/* This was generated from enumvalueDeclaration() */");
Printv(enum_code, "\n /** ", Char(doxygen_comments), " */\n", NIL);
Delete(doxygen_comments);
}

if (csattributes)
Printf(enum_code, " %s\n", csattributes);

Printf(enum_code, " %s", symname);
Expand All @@ -1381,7 +1452,16 @@ class CSHARP:public Language {
Printf(enum_code, " = %s", value);
}
} else {
// Wrap C/C++ enums with constant integers or use the typesafe enum pattern
//translate and write comment if flagged
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, " ");
if (comment_creation_chatter)
Printf(enum_code, "/* This was generated from enumvalueDeclaration() */");
Printv(enum_code, "\n /** ", Char(doxygen_comments), " */\n", NIL);
Delete(doxygen_comments);
}

// Wrap C/C++ enums with constant integers or use the typesafe enum pattern
SwigType *typemap_lookup_type = parent_name ? parent_name : NewString("enum ");
Setattr(n, "type", typemap_lookup_type);
const String *tm = typemapLookup(n, "cstype", typemap_lookup_type, WARN_CSHARP_TYPEMAP_CSWTYPE_UNDEF);
Expand Down Expand Up @@ -1434,6 +1514,22 @@ class CSHARP:public Language {
return SWIG_OK;
}

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

* file
* ------------------------------------------------------------------------ */
virtual int doxygenComment(Node* n) {
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, 0);
if (comment_creation_chatter)
Printf(structuralComments, "/* This was generated from doxygenComment() */");
Printv(structuralComments, "/** ", Char(doxygen_comments), " */\n", NIL);
Delete(doxygen_comments);
}
return SWIG_OK;
}

/* -----------------------------------------------------------------------
* constantWrapper()
* Used for wrapping constants - #define or %constant.
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, " ");
if (comment_creation_chatter)
Printf(constants_code, "/* This was generated from constantWrapper() */");
Printv(constants_code, " /** ", Char(doxygen_comments), " */ ", NIL);
Delete(doxygen_comments);
}

bool is_enum_item = (Cmp(nodeType(n), "enumitem") == 0);

const String *itemname = (proxy_flag && wrapping_member_flag) ? variable_name : symname;
Expand Down Expand Up @@ -1861,6 +1966,15 @@ class CSHARP:public Language {
Printv(proxy_class_def, typemapLookup(n, "csimports", typemap_lookup_type, WARN_NONE), // Import statements
"\n", NIL);

// translate and write comment if flagged
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, 0);
if (comment_creation_chatter)
Printf(proxy_class_def, "/* This was generated from emitProxyClassDefAndCPPCasts() */");
Printv(proxy_class_def, " /** ", Char(doxygen_comments), " */ \n", NIL);
Delete(doxygen_comments);
}

// Class attributes
const String *csattributes = typemapLookup(n, "csattributes", typemap_lookup_type, WARN_NONE);
if (csattributes && *Char(csattributes))
Expand Down Expand Up @@ -2602,7 +2716,17 @@ class CSHARP:public Language {
Swig_warning(WARN_CSHARP_TYPEMAP_CSOUT_UNDEF, input_file, line_number, "No cstype typemap defined for %s\n", SwigType_str(cvariable_type, 0));
}
}
const String *csattributes = Getattr(n, "feature:cs:attributes");

// translate and write comment if flagged
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, " ");
if (comment_creation_chatter)
Printf(function_code, "/* This was generated from proxyclassfunctionhandler() */");
Printv(function_code, " /** ", Char(doxygen_comments), " */ \n", NIL);
Delete(doxygen_comments);
}

const String* csattributes = Getattr(n, "feature:cs:attributes");
if (csattributes)
Printf(proxy_class_code, " %s\n", csattributes);
const String *methodmods = Getattr(n, "feature:cs:methodmodifiers");
Expand Down Expand Up @@ -2685,6 +2809,15 @@ class CSHARP:public Language {
String *mangled_overname = Swig_name_construct(getNSpace(), overloaded_name);
String *imcall = NewString("");

// translate and write comment if flagged
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, " ");
if (comment_creation_chatter)
Printf(function_code, "/* This was generated from constructionhandler() */");
Printv(function_code, " /** ", Char(doxygen_comments), " */ \n", NIL);
Delete(doxygen_comments);
}

const String *csattributes = Getattr(n, "feature:cs:attributes");
if (csattributes) {
Printf(function_code, " %s\n", csattributes);
Expand Down Expand Up @@ -2988,6 +3121,15 @@ class CSHARP:public Language {
String *post_code = NewString("");
String *terminator_code = NewString("");

// translate and write comment if flagged
if (doxygen && doxygenTranslator->hasDocumentation(n)) {
String* doxygen_comments = doxygenTranslator->getDocumentation(n, " ");
if (comment_creation_chatter)
Printf(function_code, "/* This was generated from moduleClassFunctionHandler() */");
Printv(function_code, " /** ", doxygen_comments, " */\n", NIL);
Delete(doxygen_comments);
}

if (l) {
if (SwigType_type(Getattr(l, "type")) == T_VOID) {
l = nextSibling(l);
Expand Down Expand Up @@ -4585,6 +4727,9 @@ extern "C" Language *swig_csharp(void) {

const char *CSHARP::usage = "\
C# Options (available with -csharp)\n\
-doxygen - Convert C++ doxygen comments to JavaDoc comments in proxy classes\n\
-debug-doxygen-parser - Display doxygen parser module debugging information\n\
-debug-doxygen-translator - Display doxygen translator module debugging information\n\
-dllimport <dl> - Override DllImport attribute name to <dl>\n\
-namespace <nm> - Generate wrappers into C# namespace <nm>\n\
-noproxy - Generate the low-level functional interface instead\n\
Expand Down