From 4acd76cee98aa0a49b4d159e4986b24df8491f49 Mon Sep 17 00:00:00 2001 From: Lleyton Gray Date: Thu, 23 Mar 2023 18:16:47 -0700 Subject: girwriter: Write filename, line, and column attributes for doc elements See https://gitlab.gnome.org/GNOME/vala/issues/707 --- codegen/valagirwriter.vala | 72 +++++++++++++----------- valadoc/tests/girwriter/GirTest-1.0.gir-expected | 62 ++++++++++---------- 2 files changed, 71 insertions(+), 63 deletions(-) diff --git a/codegen/valagirwriter.vala b/codegen/valagirwriter.vala index 01987d4fc..5bfece823 100644 --- a/codegen/valagirwriter.vala +++ b/codegen/valagirwriter.vala @@ -260,10 +260,18 @@ public class Vala.GIRWriter : CodeVisitor { this.context = null; } - private void write_doc (string? comment) { + private void write_doc (string? comment, Comment? symbol = null) { if (comment != null) { write_indent (); - buffer.append (""); + if (symbol != null) { + var filename = symbol.source_reference.file.get_relative_filename(); + var line = symbol.source_reference.begin.line; + var column = symbol.source_reference.begin.column; + + buffer.append_printf ("", filename, line, column); + } else { + buffer.append (""); + } buffer.append (comment); buffer.append ("\n"); } @@ -452,7 +460,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_class_comment (cl)); + write_doc (get_class_comment (cl), cl.comment); // write implemented interfaces foreach (DataType base_type in cl.get_base_types ()) { @@ -614,7 +622,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_class_comment (cl)); + write_doc (get_class_comment (cl), cl.comment); hierarchy.insert (0, cl); cl.accept_children (this); @@ -657,7 +665,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_struct_comment (st)); + write_doc (get_struct_comment (st), st.comment); hierarchy.insert (0, st); st.accept_children (this); @@ -698,7 +706,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_interface_comment (iface)); + write_doc (get_interface_comment (iface), iface.comment); // write prerequisites if (iface.get_prerequisites ().size > 0) { @@ -870,7 +878,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_enum_comment (en)); + write_doc (get_enum_comment (en), en.comment); enum_value = 0; hierarchy.insert (0, en); @@ -909,7 +917,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (comment); + write_doc (comment, ev.comment); indent--; write_indent (); @@ -942,7 +950,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_error_domain_comment (edomain)); + write_doc (get_error_domain_comment (edomain), edomain.comment); enum_value = 0; hierarchy.insert (0, edomain); @@ -974,7 +982,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (comment); + write_doc (comment, ecode.comment); indent--; write_indent (); @@ -1006,7 +1014,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_constant_comment (c)); + write_doc (get_constant_comment (c), c.comment); write_type (initializer.value_type); @@ -1037,7 +1045,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_field_comment (f)); + write_doc (get_field_comment (f), f.comment); write_type (f.variable_type); @@ -1092,16 +1100,16 @@ public class Vala.GIRWriter : CodeVisitor { private void write_implicit_params (DataType? type, ref int index, bool has_array_length, string? name, ParameterDirection direction) { if (type is ArrayType && has_array_length) { for (var i = 0; i < ((ArrayType) type).rank; i++) { - write_param_or_return (((ArrayType) type).length_type, "parameter", ref index, has_array_length, "%s_length%i".printf (name, i + 1), null, direction); + write_param_or_return (((ArrayType) type).length_type, "parameter", ref index, has_array_length, "%s_length%i".printf (name, i + 1), null, null, direction); } } else if (type is DelegateType) { var deleg_type = (DelegateType) type; if (deleg_type.delegate_symbol.has_target) { var data_type = new PointerType (new VoidType ()); - write_param_or_return (data_type, "parameter", ref index, false, "%s_target".printf (name), null, direction); + write_param_or_return (data_type, "parameter", ref index, false, "%s_target".printf (name), null, null, direction); if (deleg_type.is_disposable ()) { var notify_type = new DelegateType (context.root.scope.lookup ("GLib").scope.lookup ("DestroyNotify") as Delegate); - write_param_or_return (notify_type, "parameter", ref index, false, "%s_target_destroy_notify".printf (name), null, direction); + write_param_or_return (notify_type, "parameter", ref index, false, "%s_target_destroy_notify".printf (name), null, null, direction); } } } @@ -1158,7 +1166,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf ("\n", tag_type); } - private void write_params_and_return (string tag_name, List params, List? type_params, DataType? return_type, bool return_array_length, string? return_comment = null, bool constructor = false, Parameter? instance_param = null, bool user_data = false) { + private void write_params_and_return (Callable symbol, string tag_name, List params, List? type_params, DataType? return_type, bool return_array_length, string? return_comment = null, bool constructor = false, Parameter? instance_param = null, bool user_data = false) { int last_index = 0; bool ret_is_struct = return_type != null && return_type.is_real_non_null_struct_type (); @@ -1184,9 +1192,9 @@ public class Vala.GIRWriter : CodeVisitor { } if (return_type != null && !ret_is_struct) { - write_param_or_return (return_type, "return-value", ref last_index, return_array_length, null, return_comment, ParameterDirection.IN, constructor); + write_param_or_return (return_type, "return-value", ref last_index, return_array_length, null, symbol.comment, return_comment, ParameterDirection.IN, constructor); } else if (ret_is_struct) { - write_param_or_return (new VoidType (), "return-value", ref last_index, false, null, return_comment, ParameterDirection.IN); + write_param_or_return (new VoidType (), "return-value", ref last_index, false, null, symbol.comment, return_comment, ParameterDirection.IN); } if (params.size != 0 || (type_params != null && type_params.size > 0) || instance_param != null || (return_type is ArrayType && return_array_length) || (return_type is DelegateType) || ret_is_struct) { @@ -1212,7 +1220,7 @@ public class Vala.GIRWriter : CodeVisitor { if (constructor && ret_is_struct) { // struct constructor has a caller-allocates / out-parameter as instance - write_param_or_return (return_type, "instance-parameter", ref index, false, "self", return_comment, ParameterDirection.OUT, constructor, true); + write_param_or_return (return_type, "instance-parameter", ref index, false, "self", symbol.comment, return_comment, ParameterDirection.OUT, constructor, true); } if (type_params != null) { @@ -1223,14 +1231,14 @@ public class Vala.GIRWriter : CodeVisitor { } foreach (Parameter param in params) { - write_param_or_return (param.variable_type, "parameter", ref index, get_ccode_array_length (param), get_ccode_name (param), get_parameter_comment (param), param.direction, false, false, param.ellipsis || param.params_array); + write_param_or_return (param.variable_type, "parameter", ref index, get_ccode_array_length (param), get_ccode_name (param), param.parent_symbol.comment, get_parameter_comment (param), param.direction, false, false, param.ellipsis || param.params_array); write_implicit_params (param.variable_type, ref index, get_ccode_array_length (param), get_ccode_name (param), param.direction); } if (!constructor && ret_is_struct) { // struct returns are converted to parameters - write_param_or_return (return_type, "parameter", ref index, false, "result", return_comment, ParameterDirection.OUT, constructor, true); + write_param_or_return (return_type, "parameter", ref index, false, "result", symbol.comment, return_comment, ParameterDirection.OUT, constructor, true); } else if (!constructor) { write_implicit_params (return_type, ref index, return_array_length, "result", ParameterDirection.OUT); } @@ -1275,9 +1283,9 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_delegate_comment (cb)); + write_doc (get_delegate_comment (cb), cb.comment); - write_params_and_return ("callback", cb.get_parameters (), cb.get_type_parameters (), cb.return_type, get_ccode_array_length (cb), get_delegate_return_comment (cb), false, null, cb.has_target); + write_params_and_return (cb, "callback", cb.get_parameters (), cb.get_type_parameters (), cb.return_type, get_ccode_array_length (cb), get_delegate_return_comment (cb), false, null, cb.has_target); indent--; write_indent (); @@ -1399,10 +1407,10 @@ public class Vala.GIRWriter : CodeVisitor { string? return_comment = null; if (write_comment) { return_comment = get_method_return_comment (m); - write_doc (get_method_comment (m)); + write_doc (get_method_comment (m), m.comment); } - write_params_and_return (tag_name, params, m.get_type_parameters (), return_type, get_ccode_array_length (m), return_comment, false, m.this_parameter); + write_params_and_return (m, tag_name, params, m.get_type_parameters (), return_type, get_ccode_array_length (m), return_comment, false, m.this_parameter); indent--; write_indent (); @@ -1445,14 +1453,14 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_method_comment (m)); + write_doc (get_method_comment (m), m.comment); var datatype = SemanticAnalyzer.get_data_type_for_symbol (m.parent_symbol); List? type_params = null; if (m.parent_symbol is Class) { type_params = ((Class) m.parent_symbol).get_type_parameters (); } - write_params_and_return (tag_name, m.get_parameters (), type_params, datatype, false, get_method_return_comment (m), true); + write_params_and_return (m, tag_name, m.get_parameters (), type_params, datatype, false, get_method_return_comment (m), true); indent--; write_indent (); @@ -1484,7 +1492,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_property_comment (prop)); + write_doc (get_property_comment (prop), prop.comment); write_type (prop.property_type); @@ -1527,9 +1535,9 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (get_signal_comment (sig)); + write_doc (get_signal_comment (sig), sig.comment); - write_params_and_return ("glib:signal", sig.get_parameters (), null, sig.return_type, false, get_signal_return_comment (sig)); + write_params_and_return (sig, "glib:signal", sig.get_parameters (), null, sig.return_type, false, get_signal_return_comment (sig)); indent--; write_indent (); @@ -1553,7 +1561,7 @@ public class Vala.GIRWriter : CodeVisitor { } - private void write_param_or_return (DataType? type, string tag, ref int index, bool has_array_length, string? name = null, string? comment = null, ParameterDirection direction = ParameterDirection.IN, bool constructor = false, bool caller_allocates = false, bool ellipsis = false) { + private void write_param_or_return (DataType? type, string tag, ref int index, bool has_array_length, string? name = null, Comment? parent_comment = null, string? comment = null, ParameterDirection direction = ParameterDirection.IN, bool constructor = false, bool caller_allocates = false, bool ellipsis = false) { write_indent (); buffer.append_printf ("<%s", tag); if (ellipsis) { @@ -1617,7 +1625,7 @@ public class Vala.GIRWriter : CodeVisitor { buffer.append_printf (">\n"); indent++; - write_doc (comment); + write_doc (comment, parent_comment); if (ellipsis) { write_indent (); diff --git a/valadoc/tests/girwriter/GirTest-1.0.gir-expected b/valadoc/tests/girwriter/GirTest-1.0.gir-expected index 4a3620d55..77ea56b8c 100644 --- a/valadoc/tests/girwriter/GirTest-1.0.gir-expected +++ b/valadoc/tests/girwriter/GirTest-1.0.gir-expected @@ -4,15 +4,15 @@ - <para>An example comment for an example enum.</para> + <para>An example comment for an example enum.</para> - <para>An example comment for an example errordomain.</para> + <para>An example comment for an example errordomain.</para> - <para>An example comment for an example class.</para> + <para>An example comment for an example class.</para> @@ -20,21 +20,21 @@ - <para>An example comment for an example class constructor.</para> + <para>An example comment for an example class constructor.</para> - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> - <para>An example comment for an example class method.</para> + <para>An example comment for an example class method.</para> - <para>An example comment for an example return value. </para> + <para>An example comment for an example return value. </para> @@ -42,13 +42,13 @@ - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> - <para>An example comment for an example property.</para> + <para>An example comment for an example property.</para> @@ -75,13 +75,13 @@ - <para>An example comment for an example signal.</para> + <para>An example comment for an example signal.</para> - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> @@ -94,12 +94,12 @@ - <para>An example comment for an example interface.</para> + <para>An example comment for an example interface.</para> - <para>An example comment for an example interface method.</para> + <para>An example comment for an example interface method.</para> - <para>An example comment for an example return value. </para> + <para>An example comment for an example return value. </para> @@ -107,15 +107,15 @@ - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> - <para>An example comment for an example interface method.</para> + <para>An example comment for an example interface method.</para> - <para>An example comment for an example return value. </para> + <para>An example comment for an example return value. </para> @@ -123,7 +123,7 @@ - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> @@ -143,7 +143,7 @@ - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> @@ -151,13 +151,13 @@ - <para>An example comment for an example struct.</para> + <para>An example comment for an example struct.</para> - <para>An example comment for an example field.</para> + <para>An example comment for an example field.</para> - <para>An example comment for an example struct constructor.</para> + <para>An example comment for an example struct constructor.</para> @@ -166,15 +166,15 @@ - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> - <para>An example comment for an example struct method.</para> + <para>An example comment for an example struct method.</para> - <para>An example comment for an example return value. </para> + <para>An example comment for an example return value. </para> @@ -182,21 +182,21 @@ - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> - <para>An example comment for an example delegate.</para> + <para>An example comment for an example delegate.</para> - <para>An example comment for an example return value. </para> + <para>An example comment for an example return value. </para> - <para>An example comment for an example parameter. </para> + <para>An example comment for an example parameter. </para> @@ -205,11 +205,11 @@ - <para>An example comment for an example constant.</para> + <para>An example comment for an example constant.</para> - <para>An example comment for an example function.</para> + <para>An example comment for an example function.</para> -- cgit v1.2.1