docs generator - prereview

[Jiri Vanek]

On 09/08/2014 06:26 PM, Andrew Azores wrote:
> Hi,
>
> This is a huge patch and I can't say I've thoroughly and fully reviewed it, but I have at least read through it and tried to understand what's going on. Generally, I think it's okay. Even if not, this patch is so huge that making further improvements on top of this diff is going to be just incredibly unwieldy. Perhaps, if you feel that it's "good enough" as it is, it can be pushed and further refined with subsequent changesets at this point. I honestly did not take any time whatsoever to really review the "files declaration" part, assuming you mean the new PathsAndFiles class. A quick glance looks okay but that's all I can say about it.

Ty very much for brave step!

> Few very minor nits which can very well be addressed in subsequent changesets:
> - Typos! "PolicyEditorTextxsProvider" for example, or OptionsDefinitions.getPoliciEditorOptions, or TextsProvider.ITW_BUGZILAHOME

Ough. I will fix those, and seek for other before push (tomorrow morning CET)
> - OptionsDefinitions should probably have (private) data structures to group the various options by who they belong to (eg PolicyEditor vs javaws) and by if they are documented or not, etc. Then the various methods can simply be defined as various operations on these structures. Also extremely minor but I think Set might be a better ADT than List for these structures and the methods used for essentially querying them, so perhaps this can all be implemented nicely with EnumSet.

This suggestion is same approach I used in FilesDefinitions.  I was thinking abut using it

After considering the differences between option and file declaration, I decided intentionally to go by the way by which it is done now. If nothing else, It is much more simple :)

Also  the risk of not being added to any list is minimal - it can happen, But if not added to the list, then OptionsParser will not be able to parse it, so it will not happen.  So I would rather stay with this one. Teh public api of this class is very simple - get{javaws,javaws-docummented,,policieditor,itweb-settings}options...

> - Does the configure --disable-docs flag do anything to this generation step? Should it?

Nope. The reason is make . The man pages are part of it. I know javadoc to, but I'm seeing them as different things. Also the time consumption is really low comapred to javadoc.

But I'm leaving this to open discussion. We can make it dependent on --disable-docs, or have different switch for it. Anyway it can be done as separate chnage set.

Again, TYVM!

J.
>
> Thanks.
>
> ----- Original Message -----
>>
>> Hi!
>>
>>
>>    Proudly  :)  presenting... documentation generator for ITW.
>>
>> Lukas Dracz already seen the preversion, because we shares one peace of code
>> -
>> OptionsDefinitions.java  -  also he  was trying to impelmetn first versions
>> of this.
>>
>> Now his patch is built on top of this.
>>
>> Well, it does a lot of things
>> 	- generates man pages and html doc* and palintext docs**
>> 	- unified files declarations
>> 	- unified options declarations
>>
>> * html docs
>>      - are usleless in offlien mode (maybe we can publish them on classapth
>>      org after each release -
>> but are used (generated in runtime) in help dialogue - which is really really
>> nice.
>>
>> ** plain text docs - even les susefull then html docs, but are used in
>> runtime commandlinehel/and
>> about - which removed all the duplicated string providers.
>>
>> Various files and properties are sorted in javaws pages, have theyrs defaults
>> and for sure none is
>> missing.
>>
>> So finally no duplicated texts in various "about" and "help"!
>>
>>     The patch is missing localization - I'm going to do so in some next
>>     changeset, and I hope to get
>> rid of RepalcingFormater and its @@ substitution.
>>
>>
>>
>> As for review - anybody, please be specially careful about the files
>> declaration. I hope I did it
>> error-less and complete :(
>>
>>
>> The design is
>>
>> 1docprovider - have 2formater is providing 3output
>>
>> eg:
>> 1 -  itw, itw-settings,  javaws...
>> 2  - html, plain, man
>> 3 - man pages (generated during build, loclaized), runtime help - both
>> console and "nice"  html one.
>> The runtime help have evaluated varibales and properties
>>
>>
>> For runtime help I had to refactor about dialog a bit - only make some parts
>> singletons and added
>> an tab....
>>
>>
>> make check, install, dist and install form dist and unnstall works.
>>
>>
>>
>> J.
>>
>>
>>
>>
>>
>>