Menu ▾ ▴

#513 Installing procedures messes up comments

v1.1.x
fixed
Erik Hänel
None
v1.1.1
Bug Fix
2020-03-31
2020-01-24
Erik Hänel
No

Installing procedures from an install script messes up the documentation comments, if they are located in front of the procedure keyword. Also, a lot of unnecessary comments (like namespace specifics) are created, which distract the reader.

Analysis:

This requires two changes:

  • Remove the unecessary comment blocks and allow overriding the final block comment if the current procedure shall be appended. This can be done by reading the whole file, remove the comment block, truncate the file and write it again
  • Find a way to buffer documentation comments, which appear in front of procedures and append it to the procedure head, so that they may be written in advance, if found in the current string.

Implementation:

  • Implementation: The fix was implemented as proposed by the analysis.
  • Revision: [r682]
  • Implementation test: Installations with single and multiline documentation comments and multiple procedures were performed without any deviation.

Documentation:

  • ChangesLog updated
  • Code changes commented
  • Documentation articles:
    • corresponding documentation articles updated
    • new documentation articles created
    • not needed
  • Language files:
    • corresponding language files updated
    • not needed

Tests:

Fix was tested in productive environment. No deviations detected. Bug fix implemented successfully.

Related

Commit: [r682]

Discussion

  • Erik Hänel

    Erik Hänel - 2020-01-24
    • status: open --> accepted
     

  • Erik Hänel

    Erik Hänel - 2020-01-25
    • Description has changed:

    Diff:

    --- old
+++ new
@@ -1 +1,23 @@
 Installing procedures from an install script messes up the documentation comments, if they are located in front of the `procedure` keyword. Also, a lot of unnecessary comments (like `namespace` specifics) are created, which distract the reader.
+
+###Analysis:
+(*Describe, what's the issue and which changes have to be made*)
+
+###Implementation:
+* Implementation: (*Describe, what you've changed*) 
+* Revision: [rXXX]
+* Implementation test: (*Describe the type of test, which you performed, and if it was successful*)
+
+###Documentation:
+* [ ] ChangesLog updated
+* [ ] Code changes commented
+* **Documentation articles:**
+    * [ ] corresponding documentation articles updated
+    * [ ] new documentation articles created
+    * [ ] not needed
+* **Language files:**
+    * [ ] corresponding language files updated
+    * [ ] not needed
+
+###Tests:
+(*Describe, which tests you performed and their outcome*)
    • status: accepted --> analyzing
     

  • Erik Hänel

    Erik Hänel - 2020-01-25
    • Description has changed:

    Diff:

    --- old
+++ new
@@ -1,7 +1,10 @@
 Installing procedures from an install script messes up the documentation comments, if they are located in front of the `procedure` keyword. Also, a lot of unnecessary comments (like `namespace` specifics) are created, which distract the reader.

 ###Analysis:
-(*Describe, what's the issue and which changes have to be made*)
+This requires two changes:
+
+* Remove the unecessary comment blocks and allow overriding the final block comment if the current procedure shall be appended. This can be done by reading the whole file, remove the comment block, truncate the file and write it again
+* Find a way to buffer documentation comments, which appear in front of procedures and append it to the procedure head, so that they may be written in advance, if found in the current string.

 ###Implementation:
 * Implementation: (*Describe, what you've changed*)
    • status: analyzing --> implementing
     

  • Erik Hänel

    Erik Hänel - 2020-01-25
    • Description has changed:

    Diff:

    --- old
+++ new
@@ -7,19 +7,19 @@
 * Find a way to buffer documentation comments, which appear in front of procedures and append it to the procedure head, so that they may be written in advance, if found in the current string.

 ###Implementation:
-* Implementation: (*Describe, what you've changed*) 
-* Revision: [rXXX]
-* Implementation test: (*Describe the type of test, which you performed, and if it was successful*)
+* Implementation: The fix was implemented as proposed by the analysis.
+* Revision: [r682]
+* Implementation test: Installations with single and multiline documentation comments and multiple procedures were performed without any deviation.

 ###Documentation:
-* [ ] ChangesLog updated
-* [ ] Code changes commented
+* [x] ChangesLog updated
+* [x] Code changes commented
 * **Documentation articles:**
-    * [ ] corresponding documentation articles updated
+    * [x] corresponding documentation articles updated
     * [ ] new documentation articles created
     * [ ] not needed
 * **Language files:**
-    * [ ] corresponding language files updated
+    * [x] corresponding language files updated
     * [ ] not needed

 ###Tests:
    • status: implementing --> testing
     

    Related

    Commit: [r682]

  • Erik Hänel

    Erik Hänel - 2020-03-31
    • Description has changed:

    Diff:

    --- old
+++ new
@@ -23,4 +23,4 @@
     * [ ] not needed

 ###Tests:
-(*Describe, which tests you performed and their outcome*)
+Fix was tested in productive environment. No deviations detected. Bug fix implemented successfully.
    • status: testing --> fixed
     

Anonymous
Anonymous

Add attachments
Cancel