I usually need to come back to old codes that I hardly remember after some weeks of work with other projects.
I try to write comments concisely, but still codes becomes messy.
Since I work mostly with computer geometry in Visual Studio C#, I was wondering if there is any "easy" way to add image comments rather than text?
I often place such 'documentation' in a project subfolder...
Then use the local FILE:// URI convention to link that image into my code comments or ever XML markup.. with the triple slash convention... which of course shows within intelligence
A comment can certainly link to an image (as a URL for example). But no, you can't embed an image as a comment. Code files are just text, not Word documents.
If the problem is that the code isn't clear and you're relying on comments to understand it, then the solution isn't to add more comments. The solution is to write code more clearly. Give variables semantically meaningful names, extract operations (every very small ones) into semantically meaningful methods. The code itself should tell you exactly what it's doing.
Related
Is there a way to use bold or italic inside documentation comments? Something like:
/// <summary>Cleanup method. This is <b>recommended</b> way of cleanup.</summary>
public void CleanAll();
The list of predefined tags does not contain such a feature, but do you know of some way of achieving emphasis/highlighting? Preferably, if it could be shown also in tooltips when hovering over the code.
We have <c> and <code> there, but they already have their semantics.
This feature is now available in Visual Studio 2019 version 16.3.0 (release notes).
You can use the <i> or <em> tags for italic.
You can use the <b>or <strong> tags for bold.
From the release notes, a variety of html tags seem to be supported, but the official documentation doesn't seem to be updated with this new feature just yet.
It looks like this: .
OP's note: This was the accepted answer before 2019 Visual Studio update after which I accepted the other answer. This one is still useful and valid for users without that update.
Not strictly, no. However, Sandcastle (a documentation generator that generates HTML from the documentation) supports to just use HTML in there, so you can use <em> and <strong> just fine if you build it with Sandcastle.
To put it another way: As Jamiec already notes, XML documentation comments are just XML. So you can put any valid XML in there; the compiler will happily write that into the documentation XML file. It all depends on the software that processes that file. Sandcastle just passes anything it doesn't know on as HTML, since that's its output format anyway.
Visual Studio will simply ignore them when displaying the help tooltip:
ReSharper in its Ctrl+Q view will show HTML tags as text which makes things a bit ugly:
Those are usually only of concern to you if you author a library to be used by others, though. But it also means that within the IDE no one can see your emphasis as intended.
I have found actually little need for emphasis when writing API documentation; oftentimes you can write a sentence differently or restructure to have important nodes in a separate paragraph near the end, to not need emphasis at all. Consistent language and phrasing also helps readers to pick up important notes once they're used to it.
Your code probably just was an example, but I think the summary needs emphasis least of all since it only notes – in a short sentence – what a type is or a method does. If anything, use it in the remarks and even then I'd carefully consider whether you actually need it.
There are other ways of adding emphasis:
- Upper case: some BOLD text // you are shouting, but they WILL read it
- First letter: some Bold text // less emphasis
- Asterisks: some **bold** text // 2 asterisks seem to work best
- Dashes: some --bold-- text // less emphasis
Plain text is old-school, but it can be very effective - and works long after the technology has changed.
An alternate way is to use a wiki markup-like style instead.
/// <summary>Cleanup method. This is *recommended* way of cleanup.</summary>
public void CleanAll();
Edit 1:
AFAIK Visual Studio doesn't understand wiki markup. I was just suggesting to use wiki markup as a convention. Your team would still see the raw (unformatted) wiki markup in the method's intellisense.
To add clarification to the accepted answer above ('This feature is now available in Visual Studio 2019 version 16.3.0' https://stackoverflow.com/a/58227889/17203657)
From the Release Notes (https://learn.microsoft.com/en-us/visualstudio/releases/2019/release-notes-v16.3#net-productivity-163P1) 'There is now Quick Info style support for XML comments.'
Quick Info is when you hover over the method (it is NOT Intellisense), it DOES support Bold, Italic.
IntelliSense is what shows when you're adding arguments to the method, it does NOT support Bold, Italic.
As of VS 16.11.5 I've not found a way to add bolding or italics to the IntelliSense view.
Note: I do not have enough points to add this as a Comment.
I was trying to add a line break into the Intellisense display when I came across <see cref="YourReferenceHere"/> (see here), which inserts (according to the documentation) a clickable reference into the documentation. I have not figured out how to click on Intellisense tooltips, but it does provide a type-formatted/colored display which helps your reference to stand out (note that the reference must be available to Intellisense).
Side Note: I never did figure out how to do a single line break. Closest I can get is a double line break, using the <para/> tag...
I'm working on a number-crunching app with some fairly (from my POV) complex math. My first thought was,
Gee, it'd be really nice to be able to take a screen shot in
Mathematica and include it as a comment in my C# source.
I see a cdata value when entering /// alongside summary, remarks, and other options. Custom tags appear to also be supported (as there doesn't appear to be any validation happening).
In order of preference, I'd like to:
Link Mathematica code to my C# source, and have said code appear, in all its Greek-laden glory, as a comment above the method that calls it (or from which it was generated). Bonus points for actually embedding the Mathematica editor in VS!
Link to an image file containing a screenshot of the above, manually generated via Paint and the snip tool, and have VS display it.
Embed the image in a CDATA section, and have it automagically render inside of VS when viewing the code, inline with said code. Generating a base-85 (or whatever) encoded version of an image is trivial. The problem at this point is getting it to display.
Ways that this is possible:
Write an app that overlays an image on the screen and, via magic, keeps it aligned with the source view in VS. (This is ridiculous, but, hey, so is a language that requires you to denote variable names with a $, and yet has a full BNF grammar available to anyone who can Google. Oh, what a world...)
I got nothing.
Suggestions? Is it possible to extend VS so that an image, or control (where Mathematica could be hosted), can appear in the source view?
(note: one of my favorite statements is "It's software. Anything is possible. Give me a 9-volt battery, a paper clip, pocket knife and a monkey hopped up on speed, and we'll make it happen." In this case, I mean within the realm of practicality.)
It looks like this Visual Studio plug-in should solve most of your requirements:
http://visualstudiogallery.msdn.microsoft.com/793d16d0-235a-439a-91df-4ce7c721df12
If anyone knows the name for these types of comments, if one exists, please modify my question.
I frequently see comment blocks such as this:
/**********************************************
* Some Important Text Here
**********************************************/
Sometimes they can look like this:
/**********************************************
********* Some Important Text Here *******
**********************************************/
I've also seen them prettier than that.
They seem useful for noting sections of code, and important messages, such as license blocks. But, I feel like there *must* be a "lazy" way of doing this in Visual Studio, or at least an addon, because typing them manually is a pain.
Thanks!
P.S. If this feature or a point-and-click way to do it doesn't exist, then I know what VS plugin I'm writing next.
create a code snippet for them
You could perhaps look at GhostDoc, it is great for writing neat, clean, consistent style commenting in your code. It uses XML markup, and can later be exported for documentation.
If you want fixed-text blocks, then add a Code Snippet for each one you need.
If you want auto-generated documentation blocks for absolutely any code element, then you might like to try my addin, AtomineerUtils. (Similar to GhostDoc, but with significantly more features, a much better documentation generation engine, better formatting control (e.g. word wrapping of comments and documentation comments) and support for many more programming languages and documentation block styles).
You could create a toolbar macro which inserts that text at your cursor position when you click on the toolbar icon.
MS Word has this capability in its Hebrew and Arabic versions. I would like to achieve this in a windows desktop application, using .Net (may be with win-api calls).
As explained in the link provided by Otaku here, current rich text edit controls can not handle this (unless you go for the hack OP in that Q did, which did not seem like a very good solution).
You could write code to do this manually yourself, ditching the text edit control completely, but that would probably mean a lot of work. It took Microsoft years to get support for combining diacritics working properly in MSWord. I would search for open source software that has this capability, and look at how other developers have done it. It might be hard to find, though, and you would likely have to step outside .NET-land. Maybe OpenOffice can do this?
This discussion might also be of help.
I am afraid that you will find, though, that you'll have to manually parse the Unicode and assign colors to the correct glyphs. If you want to be complete, that is one heck of a job.
I have a big ASP.NET project full of hard coded strings, that now have to be extracted to resources. Such strings can be found almost anywhere (in .cs files, .aspx files, .ascx files, etc.) and the amount of files is huge. What I'm looking for is a tool (or any way) to find all these hard coded strings in one shot and put them all together in the resource file, instead of me going manually through each file. Does anything like this exist?
Note: I'm aware that it would have been better to put the strings in resources straight away when they were needed the first time, but this is a 2 years old project where nobody really cared (typical example of "not my problem" philosophy).
Thank you very much.
UPDATE: I tried CodeRush (I couldn't try RGreatEx for obvious reasons), and I'm having difficulties using it. The main issue is that the strings I'm looking for are located mainly in .aspx files, and strings in those files don't have the "Refactor to resource" command available.
For example, I can have elements like this:
<dxwgv:ASPxSummaryItem DisplayFormat="{0}" FieldName="TOTAL" ShowInColumn="Total" SummaryType="Sum" />
The part I need to change is ShowInColumn="Total" and make it like ShowInColumn="<%$ Resources:PortalResource, Total %>". This is not a string assignment in a strict way, but an attribute assignment, so the "Refactor!" command of CodeRush doesn't appear.
My target is to find all of them in one shot and change them in a specific interface (i.e. like a localization tool) instead of looking for them one by one and manually creating the corresponding resource. Refactoring one by one inside each file would be an improvement, but still very time consuming...
You could take a look at the resource refactoring tool at
http://www.codeplex.com/ResourceRefactoring
It's an instance-by-instance tool rather than a batch replacement tool. It's free and standalone so you don't need Resharper or Coderush.
Check out the new open source project VisualLocalizer on CodePlex: VisualLocalizer page. If you have some ideas, post them as issues - the project is under development and we welcome feedback.
VisualStudio lets you search and replace with RegEx. It won't be the "fix all in one shot" solution, but it should cut back on the amount manual work significantly.
Just a thought.
If you have a look at DevExpress' CodeRush it has the functionaility you are looking for, you may need to automate it to do it a all in one shot.
It has a great deal more too!
Kindness,
Dan
Try RGreatEx. This is a plugin for ReSharper:
RGreatEx is the most powerful localizer and coding helper for Visual Studio. Once installed, it lets you localize .NET applications and produce safer code, saving up to 95% of time the developer usually spends on doing the same by hand. Empower yourself with time-saving refactorings, such as "Move to resource" and "Rename resource". The plug-in will automatically analyze string and resource usage and suggest moving strings to resources.
Do you have ReSharper? Then you perhaps should wait for version 5.0. It will have RGreatEx (mentioned by Anton) functionality included. Read the thread from the R# forum on this topic.
Update: The feature will be in R# 5.0. See the official announcement.
I've just published new tool called Jinnee.Package for string refactor. You can find it on Visual Studio gallery:
http://visualstudiogallery.msdn.microsoft.com/7ec5a225-dea4-47ae-8ebc-450d2980937f?SRC=Home