Need free VS tool which generates code documentation for me!
-
Extremely necessary if you want your SPICE or ASPICE certification.
GCS/GE d--(d) s-/+ a C+++ U+++ P-- L+@ E-- W+++ N+ o+ K- w+++ O? M-- V? PS+ PE Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X The shortest horror story: On Error Resume Next
-
this processes existing comments. it does not create the comments themselves.
CI/CD = Continuous Impediment/Continuous Despair
-
If those comments/methods are in a class library those comments could be very helpful to folks using that library.
There are no solutions, only trade-offs.
- Thomas SowellA day can really slip by when you're deliberately avoiding what you're supposed to do.
- Calvin (Bill Watterson, Calvin & Hobbes) -
Can you please suggest me a free VS tool which generates code documentation like that:
/// /// Called to calc a bid /// /// /// /// iRatedBid\[player\] private int CalcBid(HandCards hand, int player)Sandcastle: SHFB
-
If those comments/methods are in a class library those comments could be very helpful to folks using that library.
There are no solutions, only trade-offs.
- Thomas SowellA day can really slip by when you're deliberately avoiding what you're supposed to do.
- Calvin (Bill Watterson, Calvin & Hobbes)The autogenerated comments will just tell you what you already see from the name and types. Documentation is for the things you can't see directly. Personally my preferce is not having the autogenerated comment, then you do not need to waste time finding out if it tells you anything or not.
-
Can you please suggest me a free VS tool which generates code documentation like that:
/// /// Called to calc a bid /// /// /// /// iRatedBid\[player\] private int CalcBid(HandCards hand, int player)Doesn't triple clicking "/" in VS generate the comment block? /ravi
My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com
-
Thank you. Looks good but does not catch my return value?
/// Gets the hand trump cards. /// The trump card identifier. /// /// /// public List GetHandTrumpCards(int TrumpCardID) { var lopc = new List(); foreach (PlayingCard card in Cards) { if ((int)card.CardType == TrumpCardID | (int)card.CardValue == 2 | (int)card.CardValue == 3) { lopc.Add(card); } } return lopc; }The return value is not uniquely named. A method may have several return statements, and the values may be expressions, possibly different expression for each of several returns. The tool could of course create a list of all return statements. The same that you can obtain by a string search. I am not sure how useful that would be.
Religious freedom is the freedom to say that two plus two make five.
-
The return value is not uniquely named. A method may have several return statements, and the values may be expressions, possibly different expression for each of several returns. The tool could of course create a list of all return statements. The same that you can obtain by a string search. I am not sure how useful that would be.
Religious freedom is the freedom to say that two plus two make five.
-
The autogenerated comments will just tell you what you already see from the name and types. Documentation is for the things you can't see directly. Personally my preferce is not having the autogenerated comment, then you do not need to waste time finding out if it tells you anything or not.
I took this to be a framework for filling in you more descriptive comments, such as Set of cards currently held by 'bidder' (I can imagine even more helpful explanations that this, especially if I knew more of the context.) Without any explanation, just formatting the method prototype in a different layout, is meaningless.
Religious freedom is the freedom to say that two plus two make five.
-
I never used this tool, but OP presents an example where it doesn't catch his 'return lopc;', leaving only
/// ///
///in the 'documentation'. I am one of those who likes to get out of here as soon as the job is done; I detest the 'single exit point' style that could increase the block nesting level by half a dozen or more. In other words: Some methods can have half a dozen or more return statements. You might want to have them all listed above the method prototype; I think it messes it up. With several exits, the reason for leading to that exit is frequently far more essential than the exit value - especially if it is in the class of 'success' or 'failure'! Seeing four 'return failure' and two 'return success' in the documentation is not really informative. Seeing 'return lopc' makes very little sense until you have studied the actual code, seeing how lopc is built, but then you hardly need the documentation telling that lopc is returned! If you use the template for filling in a brief explanation of what it takes to succeed, or in this case, what is the semantics of the subset of cards returned: Fine. I assume it applies to all the return statements, if there are several. Also, those insisting on 'single exit point' must refrain from coding any exception that might propagate out of the method. That would be an exit not through that 'single exit point', so trusting that you can catch everything immediately before your single 'return' is fooling yourself.
Religious freedom is the freedom to say that two plus two make five.
-
Can you please suggest me a free VS tool which generates code documentation like that:
/// /// Called to calc a bid /// /// /// /// iRatedBid\[player\] private int CalcBid(HandCards hand, int player)I tend to do my comments by hand. In VS, if you type
///it usually does the framework for you, including params and return types. Here is a handy reference for the recommendations and also XML tags: Documentation comments - document APIs using /// comments - C# | Microsoft Learn[^]. The link also includes Tools that accept XML documentation input[^] for generating documentation.Graeme
"I fear not the man who has practiced ten thousand kicks one time, but I fear the man that has practiced one kick ten thousand times!" - Bruce Lee
-
I tend to do my comments by hand. In VS, if you type
///it usually does the framework for you, including params and return types. Here is a handy reference for the recommendations and also XML tags: Documentation comments - document APIs using /// comments - C# | Microsoft Learn[^]. The link also includes Tools that accept XML documentation input[^] for generating documentation.Graeme
"I fear not the man who has practiced ten thousand kicks one time, but I fear the man that has practiced one kick ten thousand times!" - Bruce Lee
VS refuses return info as well for me. And comment "Nons the trump cards." is pointless.
/// /// Nons the trump cards. /// /// The hand. /// The trump identifier. /// public static string NonTrumpCards(HandCards hand, int TrumpID) { return hand.GetHandExTrumpString(TrumpID); } -
VS refuses return info as well for me. And comment "Nons the trump cards." is pointless.
/// /// Nons the trump cards. /// /// The hand. /// The trump identifier. /// public static string NonTrumpCards(HandCards hand, int TrumpID) { return hand.GetHandExTrumpString(TrumpID); }Hmmm... Try this extension: Extended XML Doc Comments Provider (VS2022+) - Visual Studio Marketplace[^]
Graeme
"I fear not the man who has practiced ten thousand kicks one time, but I fear the man that has practiced one kick ten thousand times!" - Bruce Lee
-
VS refuses return info as well for me. And comment "Nons the trump cards." is pointless.
/// /// Nons the trump cards. /// /// The hand. /// The trump identifier. /// public static string NonTrumpCards(HandCards hand, int TrumpID) { return hand.GetHandExTrumpString(TrumpID); }>And comment "Nons the trump cards." is pointless. Not necessarily. Change the XML comment style to font color red, bold, and voila, you can scroll through your code with all information needed visible in the same place, same style. Side note: My Delphi 7 maintenance mode has three colors, bold red for comments, bold green for strings and bold/normal gray for the rest, on black background. It is perfect to find where to modify the code.
-
Can you please suggest me a free VS tool which generates code documentation like that:
/// /// Called to calc a bid /// /// /// /// iRatedBid\[player\] private int CalcBid(HandCards hand, int player)From reading the question and replies to which the OP has also replied, I understand that the OP wants a tool to generate the xmldoc example given. And the only question I have is what value this "documentation" has? It tells you nothing you couldn't already glean from the signature. It's "documentation" like this which drives the "no comments" movement - because this is just more reading material for the consumer - it does absolutely nothing to explain the _why_ or the methodology of the decorated function. It will rot because it's been noise ever since it was introduced, so at some point, it won't tell you something obvious - it will just be a source of "WAT?!" for the reader. I'm incredibly dismayed at people looking for tools to do this and write their unit tests for them. Are we even craftspeople any more? Do you consider yourself a creator, or a button-pusher?
------------------------------------------------ If you say that getting the money is the most important thing You will spend your life completely wasting your time You will be doing things you don't like doing In order to go on living That is, to go on doing things you don't like doing Which is stupid. - Alan Watts https://www.youtube.com/watch?v=-gXTZM\_uPMY
-
From reading the question and replies to which the OP has also replied, I understand that the OP wants a tool to generate the xmldoc example given. And the only question I have is what value this "documentation" has? It tells you nothing you couldn't already glean from the signature. It's "documentation" like this which drives the "no comments" movement - because this is just more reading material for the consumer - it does absolutely nothing to explain the _why_ or the methodology of the decorated function. It will rot because it's been noise ever since it was introduced, so at some point, it won't tell you something obvious - it will just be a source of "WAT?!" for the reader. I'm incredibly dismayed at people looking for tools to do this and write their unit tests for them. Are we even craftspeople any more? Do you consider yourself a creator, or a button-pusher?
------------------------------------------------ If you say that getting the money is the most important thing You will spend your life completely wasting your time You will be doing things you don't like doing In order to go on living That is, to go on doing things you don't like doing Which is stupid. - Alan Watts https://www.youtube.com/watch?v=-gXTZM\_uPMY
Davyd McColl wrote:
And the only question I have is what value this "documentation" has?
Maybe a formal requirement?
den2k88 wrote:
Extremely necessary if you want your SPICE or ASPICE certification.
I have been working under coding standard regimes requiring the arguments to be repeated ("prepeated"?) above the function declaration in a formal syntax, regardless of certifications. Mostly it has been so that if anyone asks for documentation of the source code, the company can proudly present a huge PDF document, split into main sections for each namespace, main chapters for the classes and sometimes each method has been given a separate page for describing its invocation interface and arguments. All is automatically generated from the formatted comments. It is useful for nothing except that it allows you to state, without lying: "Of course we maintain full documentation of the source code".
Religious freedom is the freedom to say that two plus two make five.
-
Davyd McColl wrote:
And the only question I have is what value this "documentation" has?
Maybe a formal requirement?
den2k88 wrote:
Extremely necessary if you want your SPICE or ASPICE certification.
I have been working under coding standard regimes requiring the arguments to be repeated ("prepeated"?) above the function declaration in a formal syntax, regardless of certifications. Mostly it has been so that if anyone asks for documentation of the source code, the company can proudly present a huge PDF document, split into main sections for each namespace, main chapters for the classes and sometimes each method has been given a separate page for describing its invocation interface and arguments. All is automatically generated from the formatted comments. It is useful for nothing except that it allows you to state, without lying: "Of course we maintain full documentation of the source code".
Religious freedom is the freedom to say that two plus two make five.
and people wonder why, when there is documentation, a lot of the time, it completely sucks ): fwiw, typing `///` in Rider (and, I'd assume, in VS, using ReSharper) automatically inserts an xmldoc skeleton, like so: ```C# /// /// /// /// /// /// public int Add(int a, int b) { return a + b; } ``` so one could do the following, which I do in my personal library projects because I'd like there to be intellisense documentation, and some day I'll find a tool that generates a nice html site out of that xmldoc (there are some, but I haven't found one that is free and any good - I may have to resort to writing my own): 1. enable xmldocumentation in the project 2. update the csproj, as early as possible, with: ```XML true true ``` 3. When creating a new method, or in response to build failure, do a triple-slash over the method and try to think of anything useful that could go in the summary. Sometimes it will be obvious, eg "Adds a and b and returns the result" - but I find that having to think about it, a lot of the time, there are useful summaries against my methods. I want full xmldoc for my users, but I agree there are times when the method seems quite obvious - so this is what I do there. At least following the above instead of just running a tool invokes the random chance that your documentation is actually useful. Certifications that require documentation without any stipulation of usefulness seem like a complete waste of time: - for the OP, certifiers and the users. - OP has to run a tool or write some code. - Certifiers have to check the output. Users have to use external code essentially blind - esp in an example like OPs where the actual intent is not at all obvious from the method name, at least not to a person who isn't "on the inside" with OP's terminology, and I'm 100% sure that a more useful doc string could be thought of there. Running a tool to produce this useless documentation runs counter to the original intent of the certification too. If I were a certifier and saw that was what was going on, I'd fail the project /2c
------------------------------------------------ If you say that getting the money is the most important thing You will spend your life completely wasting your time You will
-
Hmmm... Try this extension: Extended XML Doc Comments Provider (VS2022+) - Visual Studio Marketplace[^]
Graeme
"I fear not the man who has practiced ten thousand kicks one time, but I fear the man that has practiced one kick ten thousand times!" - Bruce Lee
-
Can you please suggest me a free VS tool which generates code documentation like that:
/// /// Called to calc a bid /// /// /// /// iRatedBid\[player\] private int CalcBid(HandCards hand, int player)Atomineer is not free, but it's not expensive, either. It has a very high degree of customizability along with being very good at determining code function from element names. Documentation can be applied at various scopes, from a single element to an entire file, and limited to public members or applied to all. I have been using it for years and have been very pleased with it.
-
Can you please suggest me a free VS tool which generates code documentation like that:
/// /// Called to calc a bid /// /// /// /// iRatedBid\[player\] private int CalcBid(HandCards hand, int player)
