Information page on how to handle `element` documentation and `obsolete` objects.

[thabaum]

Description of documentation change

Is your documentation request related to existing documentation or new documentation? Provide a clear and concise description of the requested documentation change.

1. Documentation on how to document elements for DNN Platform.

DNN Journal Module currently has many undocumented elements. Looks like some help could be needed in places that don't get touched much.

This would cut down on the number of build warnings allowing community maintenance programmers (like myself) to focus more on obsolete functions while things are being updated between DNN Platform versions obsolete objects updating those to utilize the new DNN Platform logic.

How to report the issue along with explanation on how to fix the issue when those types of issues come to light.

2. This should be potentially another issue created. If possible, it would also be nice in the same area to have a little something about obsolete items that need migrated, a little info on how to handle them with most detail for things that we have a lot of work to do on.

Existing documentation URL (if applicable)

Provide URL to existing documentation.

Could be located here on the home page with an explanation on API section and how to document an element to be included here. Process maybe just to submit the request on GitHub.

Existing documentation section (if applicable)

Provide the name of the documentation section to be changed. DNN Journal Module has many undocumented elements. Looks like some help could be needed in places that don't get touched much.

Proposed area for new documentation (if applicable)

Provide the area in which the proposed new documentation should reside.

To document an element do the following:

1. First do this.
2. Next do this.
3. Finally do this.

Screenshots

If applicable, provide screenshots to help explain your documentation request.

journalcontrollerimp.cs among other files may have obsolete objects like this namespace.

Additional context

I will help as I can. I don't want to ask again or look for some thread where I posted about it. I believe this API homepage should be filled with helpful tips about how to work with the API documentation. Each section should have an introduction which could include submitting a PR for missing elements including this specific information. And to submit a PR with this specific information completed for this section.

Here is a link to me asking our community senior DNN Platform developers how to handle a commonly obsolete object. DNN Platform Discussion 4091

[valadas]

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.

[thabaum]

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.

[valadas]

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/

[valadas]

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...

[valadas]

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.