Information page on how to handle `element` documentation and `obsolete` objects. about dnndocs HOT 5 OPEN

I don't know that this needs to be part of DNNDocs, basically the best way to handle this is to submit documentation PRs to DnnPlatform to document those undocumented methods. DNNDocs automatically will pickup those XML docs.

from dnndocs.

OK, I am always in the wrong spot 💯

I need to learn how to do this. Which is what I felt could be a part of the docs. I do not know where to start to be honest when properly documenting a method and asking seems redundant for maintainers to need to provide an answer for.

I was thinking this would be a great place to show the process, or a link to the process of submitting a documentation request for the undocumented methods.

Something under the contribution documentation section with a link going to there from here so we all know how to contribute to this area of the DNN Platform properly would suffice. I would love just a simple link for a reply when asking or if someone asks how to document DNN Platform methods. Then we can all refer a link if that makes sense with general instructions.

from dnndocs.

I need to learn how to do this

Oh it is pretty simple, let's take a sample: https://github.com/valadas/Dnn.Platform/blob/develop/DNN%20Platform/DotNetNuke.Web/Api/Auth/BasicAuthMessageHandler.cs

This shows up in DNNDocs automagically here https://docs.dnncommunity.org/api/DotNetNuke.Web.Api.Auth.AuthMessageHandlerBase.html

It is driven by xml docs above public members (methods, constructions, type declarations, properties, enums, etc.)
You basically start by typing in Visual Studio 3 slashes above the member /// and Visual Studio will create a block for your with placeholder for everything you need to document (summary, parameters, return types, etc.) and you just fill in the blanks. Upon next docs build, this will be pulled into DNN docs.

There are some more advanced options too which you can read all about here https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/

from dnndocs.

Oh and if a class inherits from another one, it's nice to document the parent class (or interface) first and then do a <inheritdoc /> on the inherited members if the parent documentation still makes sense, that reduces documentation maintenance with a "single source of truth" if documentation fixes are in order...

from dnndocs.

VisualStudio will also help you along the way with a dropdown of the valid XML elements for docs, a popular one I use often is Exception to document what possible exceptions a method can throw so consumers know what to expect in case of troubles.

from dnndocs.