On jgrousedoc.properties

[Broofa]

Hey Denis, a hopefully quick note on the jgrousedoc.properties file.

While this file is a lot easier to work with than the old build.xml
syntax, I find I'm still having to do significant "merge"ing when new
versions of jGD come out. The reason being, mostly, that a) this file
still changes quite a bit between releases, and b) it contains a lot
of required configuration properties that aren't important (to me),
but that have to be maintained.

I feel like this file would better serve it's purpose if it it was
more streamlined, and shipped with _only_ those properties that we
know are required, or at most those properties, plus that subset of
properties that the majority of users are likely to want to change.
Any other properties that have required, well-known defaults and that
aren't likely to be changed by new users - (like "encoding" or
"useFullNames" or whatever) shouldn't even be included. (i.e. have the
defaults defined in build.xml?) To illustrate, here's my proposed
minimal version of jgrousedoc.properties:

# This file specifies the required configuration properties for
jGrouseDoc.
# For additional configuration options, please refer to:
#
# http://code.google.com/p/jgrousedoc/wiki/ConfigurationOptions

# REQUIRED! Update this to the path where you installed jGrouseDoc
jGrouseHome=/usr/local/jGrouseDoc

# The location of your source files (relative to this directory)
inputDir=.

# The directory where generated docs are placed. (Will be created
if
# necessary.)
outputDir=api

A couple things to note:
- Additional configuration properties aren't even included in
commented out form - they're documented in a wiki page. This means
the names/documentation/default settings can be changed without having
to worry about impacting existing users who aren't actually using
them. (And for those users, backward compatibility is acheived by
simply checking to see if they include the property and issuing a
suitable deprecation warning).
- Removed the ".default" suffix - I'm not really sure what that was
there for.

Thoughts?

[denis.r...@gmail.com]

As I mentioned before, there is no more need to merge
jgrousedoc.properties with new releases. That was the whole point of
doing it.
The standard build.xml has all the necessary default values, so if a
new option is added, in 99.5% of cases it would have a default value.

But I can see your point. I thought that having all the possible
config parameters in the standard file could be useful (like the
standard config file that comes with Apache server), but I guess that
could cause big deal of confusion. I will trim down the number of
options in standard jgrousedoc.properties to bare minimum.

The .default properties are required for cases when you would want to
override them from the command line. Apparently in ANT the properties
from config file have higher priority than properties from environment
variables, hence I had to introduce the ".default" ones. I will
document that aspect too.

Thanks for the feedback!

Regards,
Denis

On Mar 12, 9:37 am, Broofa <bro...@gmail.com> wrote:
> Hey Denis, a hopefully quick note on the jgrousedoc.properties file.
>
> While this file is a lot easier to work with than the old build.xml
> syntax, I find I'm still having to do significant "merge"ing when new
> versions of jGD come out. The reason being, mostly, that a) this file
> still changes quite a bit between releases, and b) it contains a lot
> of required configuration properties that aren't important (to me),
> but that have to be maintained.
>
> I feel like this file would better serve it's purpose if it it was
> more streamlined, and shipped with _only_ those properties that we
> know are required, or at most those properties, plus that subset of
> properties that the majority of users are likely to want to change.
> Any other properties that have required, well-known defaults and that
> aren't likely to be changed by new users - (like "encoding" or
> "useFullNames" or whatever) shouldn't even be included. (i.e. have the
> defaults defined in build.xml?) To illustrate, here's my proposed
> minimal version of jgrousedoc.properties:
>
> # This file specifies the required configuration properties for
> jGrouseDoc.
> # For additional configuration options, please refer to:
> #

> #http://code.google.com/p/jgrousedoc/wiki/ConfigurationOptions