View Issue Details

IDProjectCategoryView StatusLast Update
0023217CommunityOCCT:Documentationpublic2012-11-16 13:18
ReporterTimo Assigned Toilv 
PrioritynormalSeverityminor 
Status closedResolutionfixed 
Product Version6.5.3 
Target Version6.5.4Fixed in Version6.5.4 
Summary0023217: Reference documentation of V3d_TypeOf... enums is mixed up
DescriptionReference documentation of V3d_TypeOf... enums is mixed up. E.g., the text in the documentation of V3d_TypeOfAxe is taken from V3d_TypeOfUpdate.
TagsNo tags attached.
Test case number

Attached Files

  • V3d_TypeOfAxe.PNG (38,164 bytes)
  • V3d_correct.cdl (10,362 bytes)

Activities

Timo

2012-06-21 18:03

developer  

V3d_TypeOfAxe.PNG (38,164 bytes)

ilv

2012-10-12 03:09

developer   ~0021740

I noticed what documentation of all enumeration is mixed up, but documentation of classes/functions/methods are correct. I watched others cdl files with many enumerations (for example, v2d.cdl and visual3d.cdl), and in corresponding headers there are the same problem. In all enums its documentation is a incorrect.

As i understand, standart syntax of documentation in cdl: any documentation must be AFTER description of method/class/ enum/ etc.

It looks strange, but I moved documentation of all enums before its.

example:

---Purpose: Determines the type of visualization in the view, either
-- WIREFRAME or ZBUFFER (shading).
enumeration TypeOfVisualization is WIREFRAME,ZBUFFER
end TypeOfVisualization ;

and after this all headers from v3d.cdl became correct

-----

in addiction, there are some syntax error in documentation in v3d.cdl (skip symbol "-" for enum)

ilv

2012-10-12 03:09

developer  

V3d_correct.cdl (10,362 bytes)

bugmaster

2012-10-17 12:00

administrator   ~0021814

Ivan,

I told with ABV and he suggested to process all possible problem cases in cdl files that cause incorrect generation of headers with enumeration and correct syntax errors
It must be done till first week of November

Bugmaster

ilv

2012-10-23 12:06

developer   ~0021893

i fixed some bugs, please, review my code (I edited only WOK files)

1) Now documentation from ENUMERATION gets after definition of enumeration (add rule in CDL grammar yacc file)

2) fixed bug when documentation was lost due to empty comment "--\n" (edit CDL.lex file)

3)Added warning messages when documentation didn't attached to hxx files

kgv

2012-10-23 15:34

developer   ~0021903

Dear ilv, please:

- Configure e-mail in your git client according to OCCT rules.
- First line in commit description should contain the title (short description).
  Commits that contains documentation for bug itself should starts with BUG id "0023217: Short Description Of Changes or BUG title".
- Signed-off-by shouldn't appear in OCCT/WOK commits.

>if (ListOfComments()->IsEmpty() == Standard_False) {
Please avoid such comparisons for Standard_Boolean in C++ code.

>for (Standard_Integer i = 1; i <= ListOfComments()->Length(); i++ ) {
Please avoid meaningless names for variables (including iteration variables).

> WarningMsg() << "CDL" << "line " << CDLlineno << " : " << " Documentation lost " /* << aFunctionName*/ << endm;
> printf("\n");
Please describe why outputs are mixed up here? It seems that printf() should print to WarningMsg() instead.

> // all enum documentation after or in it's definition
> for(i = 1; i <= ListOfComments()->Length(); i++) {
> //Enum()->SetComment(ListOfComments()->Value(i));
> }
Here and in other places - commented code should be removed.
Appropriate description could be added instead if needed.

ilv

2012-10-24 18:13

developer   ~0021932

fixed some problems, posted by kgv

kgv

2012-10-25 16:25

developer   ~0021952

Dear ilv, please follow OCCT variables name conventions.
Prefix 'is' is reserved for boolean variables.

Patch reviewed and remarks applied - ready for testing.

bugmaster

2012-10-25 19:23

administrator   ~0021963

I tried to compile CR23217 on Mandriva2010 under occt master and got error of compilation:

Info : -------> CDLFront.cxx
Error : Errors occured in Shell
/dn44/KAS/dev/wok-CR23217-opt/src/CDLFront/CDLFront.cxx: In function 'void CheckCommentListIsEmpty(const char*)':

/dn44/KAS/dev/wok-CR23217-opt/src/CDLFront/CDLFront.cxx:648: error: 'class Handle_TCollection_HAsciiString' has no member named 'String'

Error : Failed : CDLFront.cxx
Info : -------> CDL.tab.c
Info : -------> lex.CDL.c
Info : -------> CDL.tab.c

abv

2012-11-06 13:25

manager   ~0022096

Please explain why the bug has been switched to Assigned status. If no good reason exists, please test it ASAP

bugmaster

2012-11-06 16:29

administrator   ~0022107

Reference documentation is generated correctly

bugmaster

2012-11-06 17:23

administrator   ~0022110

A lot of warnings about lost documentation are appears during extraction procedure.

bugmaster

2012-11-06 18:25

administrator   ~0022111

Fix has been integrated into occt-wok repository

- Log -----------------------------------------------------------------
commit 500f7c0256c92bced947a31e1c404871164088f8
Author: ilv <ilv@opencascade.com>
Date: Tue Nov 6 18:14:37 2012 +0400

    0023217: Reference documentation of V3d_TypeOf... enums is mixed up
    
    1) Now documentation from ENUMERATION gets after definition of enumeration
    2) fix bug when documentation was lost due to empty comment "--\n"
    
    example
    ---Purpose .....
    --
    -- some text ....
    
    3)Added warning messages when documentation didn't attached to hxx files (when you compile occt by wok)
    
    example ( v3d.cdl )
    
            class AmbientLight;
            ---Purpose: Services of ambient light sources.
    
    you can't find this documentation line in hxx files
    
    now all text print to WarningMsg(), removed printf
    
    delete commented code associated with using ListOfComments
    Coding rules applied to patch
    
    Removing output of CheckCommentListIsEmpty function

Issue History

Date Modified Username Field Change
2012-06-21 18:03 Timo New Issue
2012-06-21 18:03 Timo Assigned To => atp
2012-06-21 18:03 Timo File Added: V3d_TypeOfAxe.PNG
2012-09-03 14:29 atp Assigned To atp => bugmaster
2012-10-03 11:02 bugmaster Assigned To bugmaster => ilv
2012-10-03 11:02 bugmaster Status new => assigned
2012-10-12 03:07 ilv Assigned To ilv => Timo
2012-10-12 03:08 ilv Assigned To Timo => ilv
2012-10-12 03:09 ilv Note Added: 0021740
2012-10-12 03:09 ilv File Added: V3d_correct.cdl
2012-10-17 12:00 bugmaster Note Added: 0021814
2012-10-23 12:06 ilv Note Added: 0021893
2012-10-23 12:14 ilv Assigned To ilv => abv
2012-10-23 12:22 ilv Status assigned => resolved
2012-10-23 15:34 kgv Note Added: 0021903
2012-10-23 15:39 kgv Assigned To abv => ilv
2012-10-23 15:39 kgv Status resolved => assigned
2012-10-24 15:48 abv Target Version => 6.6.0
2012-10-24 15:49 abv Target Version 6.6.0 => 6.5.4
2012-10-24 18:13 ilv Note Added: 0021932
2012-10-24 18:13 ilv Assigned To ilv => abv
2012-10-24 18:13 ilv Status assigned => resolved
2012-10-24 18:57 abv Assigned To abv => kgv
2012-10-25 16:25 kgv Note Added: 0021952
2012-10-25 16:25 kgv Assigned To kgv => ibs
2012-10-25 16:25 kgv Status resolved => reviewed
2012-10-25 19:23 bugmaster Note Added: 0021963
2012-10-25 19:23 bugmaster Assigned To ibs => ilv
2012-10-25 19:23 bugmaster Status reviewed => assigned
2012-10-25 19:41 bugmaster Assigned To ilv => ibs
2012-10-26 09:08 kgv Status assigned => resolved
2012-10-26 09:08 kgv Status resolved => reviewed
2012-10-31 09:57 mkv Assigned To ibs => ilv
2012-10-31 09:57 mkv Status reviewed => assigned
2012-11-06 13:25 abv Note Added: 0022096
2012-11-06 13:25 abv Assigned To ilv => mkv
2012-11-06 13:25 abv Status assigned => feedback
2012-11-06 14:38 bugmaster Assigned To mkv => bugmaster
2012-11-06 16:29 bugmaster Note Added: 0022107
2012-11-06 16:29 bugmaster Status feedback => tested
2012-11-06 17:23 bugmaster Note Added: 0022110
2012-11-06 17:23 bugmaster Status tested => feedback
2012-11-06 17:23 bugmaster Assigned To bugmaster => ilv
2012-11-06 18:25 bugmaster Status feedback => tested
2012-11-06 18:25 bugmaster Note Added: 0022111
2012-11-06 18:25 bugmaster Status tested => verified
2012-11-06 18:25 bugmaster Resolution open => fixed
2012-11-16 13:13 bugmaster Fixed in Version => 6.5.4
2012-11-16 13:18 bugmaster Status verified => closed