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.

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

Insert a newline for empty single-line documentation comments #917

Merged

Conversation

maffeus
Copy link
Contributor

@maffeus maffeus commented Jan 29, 2025

This PR makes empty single-line documentation comments act as newlines.
This change fixes #905 and aligns single-line comments with multi-line comments, making them essentially equivalent as far as I can tell.

--- @class MyClass
---
--- A sample class.
local MyClass = {}
MyClass.__index = MyClass

image

--[=[
	@class MyClass

	A sample class.
]=]
local MyClass = {}
MyClass.__index = MyClass

image

@JohnnyMorganz
Copy link
Owner

Thanks for this! Can you also add a test case to Documentation.test.cpp?

@JohnnyMorganz
Copy link
Owner

Whoops, wrong button

@JohnnyMorganz JohnnyMorganz reopened this Feb 1, 2025
@maffeus
Copy link
Contributor Author

maffeus commented Feb 1, 2025

I'm not sure if this is the best way to add a test like this, because I feel like this is a much more complicated and nuanced test. Probably what would need to happen is every use of multiline comments (or vice versa) in Documentation.test.cpp should be replaced with a use of both (?) and check if their results are equal, but that just seems terrible to implement, and I'm not going to change the entire codebase for just that. 😓

Ideally, the end goal should probably always be congruence between multiline and single-line doc comments, such that someone could replace the --- with tabs, and add the --[=[ prefix and ]=] suffix and be left with the same rendered result no matter what. I'm just not sure how you would test such a thing without just testing both multiline and single-line doc comments for every test case.

@JohnnyMorganz
Copy link
Owner

This test makes sense to me! Although it looks like it is failing?

I also fixed a compilation error and added a simpler test case. I'm not sure what is the expected end result of the test you added though - it looks like the number of newlines between the singleline and multiline definitions are different?

Could you also add this to the changelog?

@maffeus
Copy link
Contributor Author

maffeus commented Feb 9, 2025

The idea was just to check if single-line documentation comments were equivalent to multi-line documentation comments but honestly the test you added is better and covers what we actually needed so I think I'll just go ahead and remove the one I made, C++ is cruel 😭

Copy link
Owner

@JohnnyMorganz JohnnyMorganz left a comment

Choose a reason for hiding this comment

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

Clear, thank you!

@JohnnyMorganz JohnnyMorganz merged commit 5c0b893 into JohnnyMorganz:main Feb 9, 2025
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Single-line comments don't add newlines
2 participants