Bug: Error parsing multiline PHPDOC @params

jamie commented

2025-02-23 09:43:24 +00:00

(Migrated from git.hazaar.io)

Problem Statement

The PHPDOC parser in Hazaar is currently unable to correctly parse multiline descriptions for @param elements in docblocks. This results in incomplete or incorrectly formatted parameter descriptions in the generated API documentation.

Steps to Reproduce

Add a multiline description to a @param annotation in a docblock.
Run the Hazaar API documentation generator.
Observe that the description is either truncated, improperly formatted, or missing in the output.

Expected Behavior

The parser should correctly capture and concatenate multiline descriptions for @param elements, preserving their intended formatting.

Actual Behavior

The parser fails to properly associate additional lines with the correct @param element.
In some cases, only the first line of the description is included, while the remaining lines are ignored or incorrectly associated.

Benefits and Risks

Benefits

Fixing this issue will ensure that function parameter descriptions are fully captured and accurately represented in the API documentation.
Improves the quality and readability of generated documentation.
Helps developers understand function parameters better by preserving full descriptions.

Risks

Modifying the parser may introduce unintended side effects if not thoroughly tested.
Edge cases in formatting (e.g., mixed indentation styles) may need to be handled carefully.

Proposed Solution

Update the PHPDOC parser to correctly detect and associate multiline descriptions with their respective @param elements.
Adjust the parsing logic to handle indentation and line continuation correctly.
Write test cases to validate correct handling of multiline @param descriptions.
Verify that other docblock elements (e.g., @return, @throws) are not affected by the changes.

## Problem Statement The PHPDOC parser in Hazaar is currently unable to correctly parse multiline descriptions for `@param` elements in docblocks. This results in incomplete or incorrectly formatted parameter descriptions in the generated API documentation. ## Steps to Reproduce 1. Add a multiline description to a `@param` annotation in a docblock. 2. Run the Hazaar API documentation generator. 3. Observe that the description is either truncated, improperly formatted, or missing in the output. ## Expected Behavior - The parser should correctly capture and concatenate multiline descriptions for `@param` elements, preserving their intended formatting. ## Actual Behavior - The parser fails to properly associate additional lines with the correct `@param` element. - In some cases, only the first line of the description is included, while the remaining lines are ignored or incorrectly associated. ## Benefits and Risks ### Benefits - Fixing this issue will ensure that function parameter descriptions are fully captured and accurately represented in the API documentation. - Improves the quality and readability of generated documentation. - Helps developers understand function parameters better by preserving full descriptions. ### Risks - Modifying the parser may introduce unintended side effects if not thoroughly tested. - Edge cases in formatting (e.g., mixed indentation styles) may need to be handled carefully. ## Proposed Solution 1. Update the PHPDOC parser to correctly detect and associate multiline descriptions with their respective `@param` elements. 2. Adjust the parsing logic to handle indentation and line continuation correctly. 3. Write test cases to validate correct handling of multiline `@param` descriptions. 4. Verify that other docblock elements (e.g., `@return`, `@throws`) are not affected by the changes.

jamie commented

2025-02-23 09:43:24 +00:00

(Migrated from git.hazaar.io)

assigned to @jamie

jamie commented

2025-02-23 09:43:29 +00:00

(Migrated from git.hazaar.io)

created branch 317-bug-error-parsing-multiline-phpdoc-params to address this issue

created branch [`317-bug-error-parsing-multiline-phpdoc-params`](/hazaar/framework/-/compare/master...317-bug-error-parsing-multiline-phpdoc-params) to address this issue

jamie commented

2025-02-23 09:43:34 +00:00

(Migrated from git.hazaar.io)

mentioned in merge request !197

jamie commented

2025-02-23 10:02:48 +00:00

(Migrated from git.hazaar.io)

mentioned in commit 0aab29e6f4

mentioned in commit 0aab29e6f46503eb50919b2e9d3296d8728b3d0c

jamie (Migrated from git.hazaar.io) closed this issue

2025-02-23 10:02:49 +00:00

jamie commented

2025-02-23 10:03:06 +00:00

(Migrated from git.hazaar.io)

Turns out the issue was with the conversion to markdown. The descriptions were being output with multiple lines, which messed with the markdown output. I have made the decision to convert multi-line @param descriptions into a single line, as multiple lines should not be used in these.

Brief and detail text will not be affected.

Turns out the issue was with the conversion to markdown. The descriptions were being output with multiple lines, which messed with the markdown output. I have made the decision to convert multi-line @param descriptions into a single line, as multiple lines should not be used in these. Brief and detail text will not be affected.

jamie self-assigned this

2025-09-04 01:14:38 +00:00

Rows
Columns

Bug: Error parsing multiline PHPDOC @params #317

Problem Statement

Steps to Reproduce

Expected Behavior

Actual Behavior

Benefits and Risks

Benefits

Risks

Proposed Solution