GNOME Bugzilla – Bug 303744
Class properties only allow single line comments
Last modified: 2005-12-31 19:27:18 UTC
The properties for class, class->operation, class->operation->parameters and attributes only allow for a single line comment. While this is sufficient for some usages, our use of the tool would benefit from having the ability to add multiple lines for a given comment.
Created attachment 46315 [details] [review] A patch for class_dialog.c which implements multi-line comments. Implements the multi-line comments for the class-dialog notebook. The multi-line dialog is implemented as a text view with-in a scroll window. I don't think it looks bad and I have done some testing on it to ensure that it works.
Created attachment 46316 [details] [review] Changes to the class.h to implement the multi-line comment This changes the structure of the class dialog to use text view instead of entry for the comment types.
If these changes are accepted, I will obviously have to change the xsl files as well to accomodate the multi-line comments. They will work as they are now except that the resulting code may need some editing to make the comments fit and to ensure that they appear as proper comments in the target language(s)
Gee, wrapping the comments wouldn't hurt either!
Setting PATCH keyword.
One problem with this patch: It doesn't enlarge the object when comments are shown, so multiline comments can go outside the bounding box and frame, leaving dirt and only getting partially rendered. Otherwise it seems ok.
Setting confirmed, still waiting for a version of the patch that updates the sizes.
I have finally had time to fix the display of multiline comments. I have chosen to use the UML standard for displaying comments. That is all comments are displayed as "{documentation = <comment> }" Following a suggestion that was in the comments for umlclass_draw, I have broken the function up into umlclass_namebox_draw, umlclass_attributesbox_draw, umlclass_operationsbox_draw and umlclass_templatebox_draw.
Created attachment 54338 [details] [review] Implements multiline comment draw with documentation tags
Created attachment 54340 [details] [review] adds the new data for multi-line comments including the new wrap spin button
Created attachment 54341 [details] [review] Not only implements multiline comments for class but adds the wrap spin button
Be aware that because of the restructuring of class.c, the patch is very large. It may not be possible to test this change by inspecting the differences affectively. It should also be noted, that due to some bugs in the implementation of objchange.c, using the class may throw execptions when manipulating the class. I will include a patch for that file but it has nothing to do with the changes to class.
Created attachment 54343 [details] [review] patch for dia/lib/objchange.c There was and expression that was using a pointer, p->member, when p was null. This corrects that problem by check p first.
Could you do your patches with -u? That makes them significantly more readable. Also please make patches that go together in one go -- if you have only one set of changes in your code, just do cvs diff -urBb in the main dia directory and it will give you a combined patch for all files with filenames included. Tried applying your patches, and while they apply cleanly, they also cause a crash when applying from the class dialog with comments and visible comments on. Don't have time to grok the create_documentation_tag function, but it does seem to have some issues with small or 0 wrap lengths. Thank you for writing extensive docs for the new methods, I really like that. Is the style you use one that some tools understand? If not, I'd prefer if you do it Javadoc-style (like in some of the files in lib (the first ones, alphabetically, so far:)).
Created attachment 54373 [details] [review] Unified patch for multi-line comments Ok here is a unified patch. I hope it is the correct format. I don't use command line cvs. I use TortoiseCVS which is a gui for cvs and the generate unified patch create this file. I have tested it and it seem to generate bit equal files from the CVS verstion. BTW I have corrected the problem with very small wrap counts. The range is now 17-200 as opposed to the original 0-200. 17 is the sise of the manditory tag.
I do appreciate your concern about the comments I have added to the class and class_dialog files. The documentation comments were not generated to facilitate an automated generation of documentation. They were created to give a maintainer of the code a hint about what is being done and follow the coding standards used in my employment. They are generated by my editing environment from a set of macros that enforce uniformity in function headers. As I intend to make many more modification to the UML objects over time, these types of headers could become more common in the UML code. If necessary, I could modify the macros to conform to the function documentation in lib. I will investigate JavaDoc but do not have any personal experience with it.
Applied the objchange and new comment patch, thanks for contributing. As for the docs, JavaDoc is pretty simple, I have no doubt your tool could implement them. See http://java.sun.com/j2se/javadoc/writingdoccomments/. If your tool is common, it is not unlikely that somebody has done it already.
2005-12-31 Hans Breuer <hans@breuer.org> * objects/UML/class.[hc] objects/UML/class_dialog.c : removed the caching of UMLClass::attributes_strings, operations_strings, templates_strings. It was broken by the recent code restructuring in bug #303744 and - if necessary at all - nowadays it should be done on the UMLAttribute, UMLOperation, UMLFormalParameter level anyway. A small, much needed simplification of the code.