Bug 61223

Summary: Enhance the documentation for mbeans-descriptors.xml
Product: Tomcat 9 Reporter: Alexis Hassler <alexis.hassler>
Component: DocumentationAssignee: Tomcat Developers Mailing List <dev>
Status: RESOLVED FIXED    
Severity: enhancement CC: kap.kumar88
Priority: P2 Keywords: Beginner
Version: unspecified   
Target Milestone: -----   
Hardware: PC   
OS: Linux   
Attachments: Updated mbeans-descriptors-howto.xml
Updated patch file for individual file as suggested.

Description Alexis Hassler 2017-06-26 05:38:46 UTC
The documentation (https://tomcat.apache.org/tomcat-9.0-doc/mbeans-descriptors-howto.html) does not describe the attributes of each mbean.

Something similar to the comments in mbeans-descriptors.dtd would be useful.
Comment 1 Kapil 2017-10-26 18:25:13 UTC
the MBeans Descriptors How To xml file has been updated.
Comment 2 Mark Thomas 2017-10-26 20:50:02 UTC
You need to attach a patch with your updates to this bug report for review.

http://www.apache.org/dev/contributors.html#patches
Comment 3 Kapil 2017-10-27 03:06:41 UTC
Created attachment 35469 [details]
Updated mbeans-descriptors-howto.xml

Updated mbeans-descriptors-howto.xml

Hope this helps, let me know for any further refinements, suggestions, recommendations.
Comment 4 Mark Thomas 2017-10-27 15:31:11 UTC
Restore state to the correct value. NEEDINFO is used when more information is required from the OP which is not the case here.

Patches should be provided in diff -u format.

I also suggest you try building the documentation and reviewing the output. It isn't going to be what you think it is.
Comment 5 Kapil 2017-11-05 16:41:55 UTC
Created attachment 35489 [details]
Updated patch file for individual file as suggested.

Updated patch file for individual file as suggested.
Comment 6 Mark Thomas 2017-11-11 21:15:09 UTC
The patch file provided is not in diff -u format. I'd expect it to look like this:
http://people.apache.org/~markt/patches/applied/2008-10-30-bug44494-regression.patch

I'll also repeat my recommendation from comment #4

I suggest you try building the documentation and reviewing the output. It isn't going to be what you think it is.

To be explicit, the format of the proposed change is broken. The rules for rendering whitespace in HTML mean that there will be a single block of unformatted text - not the table you intend.
Comment 7 Mark Thomas 2017-12-05 20:39:19 UTC
In the end, I opted to simple copy the DTD to the docs and provide a link. I thought that was better then duplicating large sections of the comments from the DTD.

Fixed in:
- trunk for 9.0.3 onwards
- 8.5.x for 8.5.25 onwards
- 8.0.x for 8.0.49 onwards
- 7.0.x for 7.0.84 onwards