Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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
Feat/improve exceptions #164
Feat/improve exceptions #164
Changes from 17 commits
6fdd796
e1b61b1
d17fd51
28cf8b0
0859f4e
5d546d0
ccadb19
a9da13f
11f89ba
3e34e46
d99ff56
c3602ad
4665b5a
d0d799a
96d22ec
d2e6ef2
955b562
e9c4ae2
4f9220f
3858c31
148e29a
62c3175
144381d
File filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
non-constant bound is dangerous
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
feel free to accompany your comment with a snippet or a suggestion for something that the offending code should be replaced with
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
None that come to mind right now without more context. I believe the first step would be to look into StripColors and StripAllTextIcons and see how we can handle it better; perhaps leave a TODO for now or a FIXME;
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I opened issue #165 for this.
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
why so? care to explain? :P
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yea but as a result of it being microsoft-specific, this comment is visible in Intellisense when you type the name of the function or variable in Visual Studio.
If you type Game::version it will print in a tooltip the content of the <summary> placed just above, making it convenient to use. I do not have the same behaviour with just
///
(although maybe there are other ways to achieve it)If you have a practical case where the XML Documentation actually poses a problem, one that I can verify, in comparison to slash code documentation (or other methods) tell me! I do not know one, but I also work predominantly with M$ tooling
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🤔
If what you mean by " 👎 " is that Visual Studio doesn't handle XML comments in Intellisense, I can provide examples where it does.
If what you mean by " 👎 " is that you know no practical downsides to using XML documentation then i'm happy to mark this conversation as resolved.
If you meant to express anything else, please use your words, I'm not fluent in "👎 " 😄
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My question is: Is there anything that XML documentation breaks in comparison to
///
? For instance, is there a widely used code editor that simply won't accept or display XML comments but would display///
comments?If this is not the case then XML comments are the way to go - a large portion of people who work with this project are using or will use Visual Studio predominantly, where having Intellisense enabled by default means XML comments do have an advantage over
///
comments. But if XML comments breaks other widely used IDEs, I don't mind considering leaving them out of the codebase.I'm looking for a practical example of XML docs presenting a problem, in a real environment - i understand the theory behind having things standard or not but it's just not something that strikes me as particularly important in that project or in that ecosystem, so practical cases where something actually breaks take priority.
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I used the XML style comments on purpose for a couple of reasons:
As mentioned by louve, one just needs to type
///
and it will automatically create the<summary>
tag and others for return types and parameters etc.Being able to distinguish them from other comments might come in handy in the future (perhaps the wiki will get a section explaining the codebase, and XML comments would make it easy for automated export and formatting).
I am aware that this is a Visual Studio specific feature, but on the other hand most people will be working on the project with this IDE anyway and will therefore benefit from it, while users of other IDEs will not have much of a disadvantage. Moreover, the XML style is just the default option in Visual Studio, there are other, more standardized options, switching to another that works for everyone would be no problem:
Having an eye-catching doc style will hopefully remind and encourage others to document their code too :D