MantisBT - Community
View Issue Details
0023217Community[OCCT] OCCT:Documentationpublic2012-06-21 18:032012-11-16 13:18
Timo 
ilv 
normalminor 
closedfixed 
[OCCT] 6.5.3 
[OCCT] 6.5.4[OCCT] 6.5.4 
0023217: Reference documentation of V3d_TypeOf... enums is mixed up
Reference documentation of V3d_TypeOf... enums is mixed up. E.g., the text in the documentation of V3d_TypeOfAxe is taken from V3d_TypeOfUpdate.
No tags attached.
png V3d_TypeOfAxe.PNG (38,164) 2012-06-21 18:03
https://tracker.dev.opencascade.org/
? V3d_correct.cdl (10,362) 2012-10-12 03:09
https://tracker.dev.opencascade.org/
Issue History
2012-06-21 18:03TimoNew Issue
2012-06-21 18:03TimoAssigned To => atp
2012-06-21 18:03TimoFile Added: V3d_TypeOfAxe.PNG
2012-09-03 14:29atpAssigned Toatp => bugmaster
2012-10-03 11:02bugmasterAssigned Tobugmaster => ilv
2012-10-03 11:02bugmasterStatusnew => assigned
2012-10-12 03:07ilvAssigned Toilv => Timo
2012-10-12 03:08ilvAssigned ToTimo => ilv
2012-10-12 03:09ilvNote Added: 0021740
2012-10-12 03:09ilvFile Added: V3d_correct.cdl
2012-10-17 12:00bugmasterNote Added: 0021814
2012-10-23 12:06ilvNote Added: 0021893
2012-10-23 12:14ilvAssigned Toilv => abv
2012-10-23 12:22ilvStatusassigned => resolved
2012-10-23 15:34kgvNote Added: 0021903
2012-10-23 15:39kgvAssigned Toabv => ilv
2012-10-23 15:39kgvStatusresolved => assigned
2012-10-24 15:48abvTarget Version => 6.6.0
2012-10-24 15:49abvTarget Version6.6.0 => 6.5.4
2012-10-24 18:13ilvNote Added: 0021932
2012-10-24 18:13ilvAssigned Toilv => abv
2012-10-24 18:13ilvStatusassigned => resolved
2012-10-24 18:57abvAssigned Toabv => kgv
2012-10-25 16:25kgvNote Added: 0021952
2012-10-25 16:25kgvAssigned Tokgv => ibs
2012-10-25 16:25kgvStatusresolved => reviewed
2012-10-25 19:23bugmasterNote Added: 0021963
2012-10-25 19:23bugmasterAssigned Toibs => ilv
2012-10-25 19:23bugmasterStatusreviewed => assigned
2012-10-25 19:41bugmasterAssigned Toilv => ibs
2012-10-26 09:08kgvStatusassigned => resolved
2012-10-26 09:08kgvStatusresolved => reviewed
2012-10-31 09:57mkvAssigned Toibs => ilv
2012-10-31 09:57mkvStatusreviewed => assigned
2012-11-06 13:25abvNote Added: 0022096
2012-11-06 13:25abvAssigned Toilv => mkv
2012-11-06 13:25abvStatusassigned => feedback
2012-11-06 14:38bugmasterAssigned Tomkv => bugmaster
2012-11-06 16:29bugmasterNote Added: 0022107
2012-11-06 16:29bugmasterStatusfeedback => tested
2012-11-06 17:23bugmasterNote Added: 0022110
2012-11-06 17:23bugmasterStatustested => feedback
2012-11-06 17:23bugmasterAssigned Tobugmaster => ilv
2012-11-06 18:25bugmasterStatusfeedback => tested
2012-11-06 18:25bugmasterNote Added: 0022111
2012-11-06 18:25bugmasterStatustested => verified
2012-11-06 18:25bugmasterResolutionopen => fixed
2012-11-16 13:13bugmasterFixed in Version => 6.5.4
2012-11-16 13:18bugmasterStatusverified => closed

Notes
(0021740)
ilv   
2012-10-12 03:09   
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)
(0021814)
bugmaster   
2012-10-17 12:00   
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
(0021893)
ilv   
2012-10-23 12:06   
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
(0021903)
kgv   
2012-10-23 15:34   
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.
(0021932)
ilv   
2012-10-24 18:13   
fixed some problems, posted by kgv
(0021952)
kgv   
2012-10-25 16:25   
Dear ilv, please follow OCCT variables name conventions.
Prefix 'is' is reserved for boolean variables.

Patch reviewed and remarks applied - ready for testing.
(0021963)
bugmaster   
2012-10-25 19:23   
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
(0022096)
abv   
2012-11-06 13:25   
Please explain why the bug has been switched to Assigned status. If no good reason exists, please test it ASAP
(0022107)
bugmaster   
2012-11-06 16:29   
Reference documentation is generated correctly
(0022110)
bugmaster   
2012-11-06 17:23   
A lot of warnings about lost documentation are appears during extraction procedure.
(0022111)
bugmaster   
2012-11-06 18:25   
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