search

maythamfahmi / CryptoNet

CryptoNet is simple, fast and a lightweight asymmetric and symmetric encryption library.
https://github.com/maythamfahmi/CryptoNet
MIT License
99 stars 20 forks source link

[feature request]: Inline documentation with description #104

Open maythamfahmi opened 1 week ago

maythamfahmi commented 1 week ago

Contact Details

No response

Is your feature request related to a problem? Please describe.

n/a

Describe the solution you'd like

It would be good a some pont when version 3 at its end, an inline documenation to be add to constructors and method.

Describe alternatives you've considered

No response

Additional context

No response

Priority Level

Low

Code of Conduct

jwdonahue commented 1 week ago

What kind of "inline" documentation?

XML comments:

/// <Summary>
/// Constructor...
/// </Summary>

Or something else?

maythamfahmi commented 1 week ago

exactly XML comments.

jwdonahue commented 1 week ago

Okay, I'll start weaving those into any work I do.

If we add: <GenerateDocumentationFile>True</GenerateDocumentationFile> to the .csproj files, then it will start issuing warnings for missing XMLDoc comments on all publicly visible members, not just the constructors.

I've been doing that in a lot of my own projects over at the SharperHack-org project. I've actually been considering keeping the comments, but dropping the XMLDoc format. That or I really need to figure out how to wire up the output xml output files, into some sort of organized set of web pages.

The thing that's always annoyed me about them, is the source comments can become difficult to read, when you start adding references or lots paragraph tags. I am starting to lean towards a more readable non-XMLDoc format for the comments, and either forgo the eventual web docs integration, or find/create a better tool for a simpler, more readable comment format.

maythamfahmi commented 5 days ago

Good input. My primary thought was about the documentation information that pops up when using IntelliSense.

jwdonahue commented 5 days ago

I'd have to verify, but I think IntelliSense picks up the summary and the listed exceptions, if the XmlDoc tags are there, but defaults to some number of whatever comments are associated with the method. At least that's the recollection I have from decades past.

But ya, I agree, developer supports are very important.