Forum: CFEngine Help Subject: Re: Documenting policy Author: sauer Link to topic: https://cfengine.com/forum/read.php?3,26480,26487#msg-26487
Just as something which might get you thinking (because I don't have code I can share)... I haven't figured out how to get cf-know or cf-report to do anything useful, so I've just been implementing a standard practice of making the last line in any promise a comment attribute. Not only does that reduce the frequency with which I screw up a comma/semicolon when adding or removing attributes, but it also lends itself to automatic documentation. I've got 2/3 of a working perl CFEngine policy parser working, and my end goal is to implement an automatic documentation-generating system. What I'm doing so far is just listing the promises under their containing bundle in sort of a tree view with the comments added. Then a few specific significant parts of the policy - like files whose permissions are managed - which get handled specially. Report promises are structured using a few consistent formats, so I can easily pull out the differnet kinds of reports based on which pattern they match. It's work better if I used methods to structure includes, as then I'd just put comments on the methods as the high-level documentstion, and allow you to drill down to lower-level documentation. But I had performance issues with that structre that I didn't like, so I've moved to dynamically building an array of includes and having one master bundle sequence with very few method promises. It performs better and I think is easier to manage, but throws a monkey wrench into my documentation. :) For more detail than what can be put into comment fields (which is all of my documentation right now, as the parser isn't done), I'm using Trac. The policy is in Subversion, and I use the Trac wiki to document things while linking in to the policy source for details. It's not auto-updating yet, but the plan is for the autodoc system to make RPC calls into Trac to update links and whatnot based on *something* - javadoc-style embedded comments, cf-know structures, or something like that. I'll cross that bridge when I come to it. _______________________________________________ Help-cfengine mailing list Help-cfengine@cfengine.org https://cfengine.org/mailman/listinfo/help-cfengine
