Andrew Bogott <[email protected]> wrote: >> I followed the little question mark help links in the puppet config >> interface in labsconsole. It leads to doc.wikimedia.org which might be >> doyxgen. >> How am I supposed to fill that documentation? I added longer comments to >> my puppet "roles" to explain the parameters. They don't show (yet). Will >> they appear when doxygen is next parsing the files? Or do I have to do >> more? What? Where?
> Fixed (sort of) by this: https://gerrit.wikimedia.org/r/#/c/47750/ > The doc headers that you wrote had a blank line between > header and class definition. That was, apparently, enough > for the puppet doc tool to think that the comments were > unrelated. > So far I've been treating 'puppet doc' as a black box and > just accepting whatever weirdness it dishes out. If things > like this start to be more of a problem then we can consider > changing the tool or adding lint checks to make sure that > puppet classes are documented usefully. It would be nice if at least all puppet classes showing up in the labsconsole interface have a docstring. For example, the "[?]" next to "base::tcptweaks" in "Add instance" di- alogs leads to an empty page. Come to think of it, actually all puppet classes should have at least a line of explana- tion. The HTML seems to be valid XML, and descriptions are tagged with '<div id="description">', but there's probably a cleaner solution for this. Tim _______________________________________________ Labs-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/labs-l
