Configurable properties
Sebastien Pouliot
Hello Gendarmes,
Today the console runner supports configurable properties by using the
rules.xml configuration file. This works well if:
a) the configurable properties are documented (so the users can
find them); and
b) the feature itself is known (i.e. documented) by the end
users.
In other words: it does not work "terribly" well since we're currently
lacking the above documentation.
However the situation is a bit more complex (than simply documenting)
because this is a feature we need to extend to other runners,
specifically GUI runners (e.g. the wizard).
The main issue is the lack of a (safe) discoverability method, i.e. not
every rules properties (even public ones) are meant as something that
can be configured by end-users.
To be useful, inside a GUI, the runner must be able discover the "real"
configurable properties _and_ it must be able to show them, in a
sensible way, to the end-user (i.e. the property name is likely not
informative enough in many cases).
So to be safely discoverable and usable by end users inside a GUI the
configurable properties
* MUST be a property;
* MUST be public;
* MUST be in a type that that implements (directly or thru
inheritance) I[Assembly|Type|Method]Rule;
* MUST be limited to basic types (e.g. string, integers,
boolean...). The runner is to ignore properties that requires
types it can't handle;
* MUST be decorated with [System.ComponentModel.Description]*;
and
* MUST be decorated with a [System.ComponentModel.DefaultValue]*
if the default is different from the type default value
Furthermore (even if this does not directly affect GUI runners) it MUST
be documented using xmldoc on the property itself, because:
1) that's the way we'll be able to push the documentation on the
wiki; and
2) that's the hint for console-runner / rules.xml users (since
discoverability does not apply to them)
See attachment for an example (patch) since it's simpler than it
sounds ;-)
Comments ? If none this will be shortly moved into the Gendarme
developer wiki documentation.
Thanks,
Sebastien
* this should not be a big surprise since it's been part of the roadmap
for a quite bit of time (currently planned for 2.8).
Cedric Vivier
Comments ? If none this will be shortly moved into the Gendarme
developer wiki documentation.
Looks great :)
Jesse Jones
On Jul 29, 2009, at 3:43 PM, Sebastien Pouliot wrote:
>
> See attachment for an example (patch) since it's simpler than it
> sounds ;-)
Why is there a doc comment on the property? I can see documenting the
framework code and maybe even the runners, but using doc comments on
the rules themselves seems like it would add a lot of clutter to the
docs and very little benefit.
>
>
>
> Comments ? If none this will be shortly moved into the Gendarme
> developer wiki documentation.
That looks like a good solution to me. Do you want me to rework my
patches to use the attributes?
-- Jesse
Sebastien Pouliot
>
> On Jul 29, 2009, at 3:43 PM, Sebastien Pouliot wrote:
>
> >
> > See attachment for an example (patch) since it's simpler than it
> > sounds ;-)
>
> Why is there a doc comment on the property?
There's is xmldoc on the property only because it's a configurable
property, i.e. the goal is not to document all properties, fields...
inside the rule. Xmldoc inside rules sole goal remains end-user
documentation.
> I can see documenting the framework code
Yes, that's also something we should do.
> and maybe even the runners,
That's unlikely (unless someone volunteers for the task). They already
contains enough "normal" comments to allow derivative runners to be
created easily.
> but using doc comments on
> the rules themselves seems like it would add a lot of clutter to the
> docs and very little benefit.
The advantages were listed in another email thread. Here's a copy of
them:
<copy+paste>
a) avoid potential typos (e.g. SuccessLowerLimit
versus SuccessLowerLimits) which would be hard to find by end users
without checking the source code. Using xmldoc will ensure the
properties are valid (well identical to what is required ;-)
b) track what is (and what needs) to the documented. If we can't list
what's documented versus what exists then there will be holes in the
documentation. We still need a tool (to ensure this) but it would be a
(much) simpler one;
c) allow the xmldoc->wiki tool to treat them specially (e.g. adding a
link to configuration documentation without having this link embedded
into each rule) and uniformly [1]
d) allow a runner to build an intelligent UI above the rules and extract
the right documentation for each configurable option [1] (e.g. a
property grid-like UI to set options). That's not some far-fetched
futuristic idea, the wizard is waiting for this to get configurable
properties.
[1] Using <list>, non-exclusively (i.e. it's being used for
other things too), inside the type <summary> would not make
these impossible but much harder to parse correctly (even if
complete and without typos) than documenting the properties
themselves;
</copy+paste>
The major, immediate (2.6), advantages are uniform (looking)
documentation (on the wiki) and ensuring there are no typo in the
property names (a+c).
Further validation* would also be simple to make (e.g. in 2.8) to ensure
all configurable properties are both correctly documented (xmldoc) and
decorated (attributes) (b)
* likely something like "rules for Gendarme rules" :)
> >
> >
> >
> > Comments ? If none this will be shortly moved into the Gendarme
> > developer wiki documentation.
>
> That looks like a good solution to me. Do you want me to rework my
> patches to use the attributes?
Yes.
Thanks
Sebastien
Jesse Jones
On Aug 2, 2009, at 8:26 AM, Sebastien Pouliot wrote:
>
> On Fri, 2009-07-31 at 08:19 -0700, Jesse Jones wrote:
>>
>> On Jul 29, 2009, at 3:43 PM, Sebastien Pouliot wrote:
>>
>>>
>>> See attachment for an example (patch) since it's simpler than it
>>> sounds ;-)
>>
>> Why is there a doc comment on the property?
>
> There's is xmldoc on the property only because it's a configurable
> property, i.e. the goal is not to document all properties, fields...
> inside the rule. Xmldoc inside rules sole goal remains end-user
> documentation.
Ya, I forgot that the xml comments are used both for documenting the
API and for generating the user level docs.
>
>
>>
-- Jesse