Document Generator Woes

Gavin_Minion · Joined: 18 Apr 2012 Posts: 10

Question: On a scale of 9 to 10 (where 9 is really awful and 10 is mind bendingly awful) where would people say the document generator currently sits? (I could do a poll, but many people find polls really annoying so you'll just have to pretend...)

After trying to get to grips with the scant documentation (Maybe they should try using the document generator!!?) I did some experiments and found the following issues:

1: Const variables always go in the variables table. Fair enough... so what goes into the local constants table...

2: the %F:DESCRIPTION% does some bizarre things - including lifting half of the code for the next function as a 'description' of the function. But somehow manages to avoid ever actually lifting any descriptive details from the function it is meant to be describing.

3: Where the comments are placed seems to have unpredictable effects on how they are treated. Inserting even a single blank line between the comments and the function header causes them to disappear from the documentation.

4: and this one was the show stopper: I defined three or four functions, laid out the comments to fit the documentation as best I could get it. Then compiled the documentation. The first function had no variables at all, the second function had the variables from the function header of the first function followed by it's own internal variables. The third function had the second functions vraiables repeated, plus one of it's own. Need I continue?

My needs are quite simple, I just want to take a bunch of comments I associate with each function and push them into a document. Without proper instructions, this documentation generator just seems to be a white elephant.

Has anyone else had any success with this or have I just wasted half a day?

jeremiah · Joined: 20 Jul 2010 Posts: 1354

I haven't even got basic stuff to work with it. I'm sure it is user error on my part, but with the very little documentation in help files, it is difficult for me to get a working output at all.

mr_Orange · Joined: 14 Apr 2012 Posts: 12

What date is your version of the document generator? Mine is dated 04-04-20212 and I will try it as soon as I receive my the proto PCB. I hope I get it working, this was one of the reasons to choose for the CCS-IDE instead of the command line version. I hope I didn't spend this extra money for not working tools...
I did ask CCS about the lines in flow chart editor but I haven't had an answer, it seems that the compiler issues have a higher priority. That issue was solved in a few hours. In the flow chart editor it is impossible to line out some of the lines which makes a messy flow chart. Messy flow chart will irritate and look clumsy so it is not very usefull to use for demonstration etc. (I think).
I hope CCS will look at their tools, they can be very usefull and I have payed for them. Perhaps a dutch saying 'Rome wasn't built in one day' applies here and I hope we can get an update when the tools are improved.

Gavin_Minion · Joined: 18 Apr 2012 Posts: 10

Hi mr_orange

I have just had a look for the version number of the document generator but I am not sure where to find it?

I could put up with the minor niggles - indeed I had spent some time removing the formatting of the document (it doesn't work and I had intended to re-format it in office once it was generated). However, when the function values start to fill with data from other functions, then it becomes useless very quickly.
If I have to spend hours proof-reading every function and moving all of the data which has been copied from the wrong function. Then checking that all of the correct data is present. I might as well have started from a blank document...

Here's hoping that CCS will one day get round to fixing this feature - and then documenting it!!!

Douglas Kennedy · Joined: 07 Sep 2003 Posts: 755 Location: Florida

Yes this CCS feature has many issues or as the Softees would say many free features. As far as the %F:DESCRIPTION% it is as free as it gets...it is unusable. The documentor will get a list of the features in your code procs variables etc which if carried over to word can save a bit of typing. The goal of placing structured comments into the xxx.c files and having it do something useful is not there yet.

mr_Orange · Joined: 14 Apr 2012 Posts: 12

Hi,

I couldn't find a version number but I looked at the date of the exe file in de picc folder. I am not sure, did you use it with an old project (previous C file) of did you start with a new C file and did put in the comments prepared for the document generator? Did you try it with a large C program or with a small program? I think I will start from small and see how it behaves.

Bert

Gavin_Minion · Joined: 18 Apr 2012 Posts: 10

Ok, my date is 24/06/2011. So yours will be more up to date than mine.
However, I fear it will make little difference as the changlog for the software does not mention any changes to the documentation generator.

Anyhow, these are not bugs I am talking about. This is seriously broken software.

I have just passed the generator a library, written in ansi C with the functions correctly declared in the header. The generator responded by creating ANOTHER seperate function description for each declaration, in addition to the description for the actual function.
Each of these had the wrong %F:DESCRIPTION% contents and none of them was actually a real function. In addition, two blank function descriptions were created (from nowhere!!?).
Until this point I had planned to forge onward without using any of the $F:xxx% stuff, but now it seems that even then, the generator will still generate a lot of rubbish.

It is almost bad enough that I should be contacting the authorities - a document generator that is incapable of generating even the most basic documentation seems like a false advert to me...

Somebody tell me how wrong I am please.....

mr_Orange · Joined: 14 Apr 2012 Posts: 12

I think you are right but I first want to test my new version, it is 10 months newer so I hope it is improved. After all on the website it says:

The compiler recognizes comments that have specially marked tags as containing information that should be exported for program documentation. The compiler associated comments with variables and functions plus the compiler accumulates information on its own about functions, variables and types. The new documentation generator uses a user generated template in .RTF format and merges in the project information from the source files and generates a .RTF output file as source code documentation.

And there is a nice print screen with even a small electronic diagram included in the document, I can't imagine that it is still not working. I will let you know how it is working for me.

Bert