Need free VS tool which generates code documentation for me!
-
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) -
In your VS project, type
/
three times and that comment will be generated, like so:
/// /// /// /// /// private int ParseLevel(string text) { -
Sure, this was already posted on Tuesday. The Lounge[^]
-
Is installed now but I do not see a menu item or context menu item for starting it. What do I miss?
Never used it myself, just looked good.
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
-
Never used it myself, just looked good.
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
-
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) -
Never used it myself, just looked good.
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
Ok, my mistake. It seems to use IntelliSense and underlines methods names and when you move with the mouse over it, you get suggestions incl. return info!
/// /// Optimizes selection. /// /// The find card. /// The player ID. /// The declarer ID. /// The game status. /// The s hand cards. /// The trump ID. /// The optimize mode. /// The wnd. /// The lead suit ID. /// A bool -
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)Thanks to all for replying! Found this for commenting methods: CodeDocumentor - Visual Studio Marketplace[^] It appears when you move the mouse over the method name (with intelli sense)
/// /// Get hand trump cards. /// /// The trump card ID. /// \]\]> public List GetHandTrumpCards(int TrumpCardID)
