FreeCADView Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0000159 | FreeCAD | Patch | public | 2010-09-20 19:34 | 2010-10-13 09:36 |
| Reporter | midgetfc | Assigned To | wmayer | ||
| Priority | normal | Severity | text | Reproducibility | N/A |
| Status | closed | Resolution | fixed | ||
| Summary | 0000159: patch to generate doxygen documentation with minimal warnings | ||||
| Description | - only about 20 benign warnings remaining when building the doc (was about 10k) - an attempt to be slightly more eye-candy - added .dox files as placeholders for out of sources additional docs Checked that it still compiles and runs. If you find the patch is too heavy, please tell me. I could make dir by dir. Cheers Midgetfc | ||||
| Tags | No tags attached. | ||||
| FreeCAD Information | |||||
|
2010-09-20 19:34
|
|
|
2010-09-21 18:26
|
|
|
|
Hello, I had forgotten two files in yesterday's patch :( Mistake corrected. I'm not sure the patch command makes this, but after applying, 5 files are supposed to be deleted (svn delete ...): src/Base/Doxygen.cpp src/App/Doxygen.cpp src/Gui/Doxygen.cpp , should be empty because their content has been moved in .dox file src/3rdParty/ANN/src/Makefile src/3rdParty/ANN/Makefile , because they are generated at configure time and, if left in repository, step systematically in every patch you make with svn diff Midgetfc |
|
|
Patch doxygen-doc-patch-r3568.gz applied in 3573. Patch doxygen-doc-patch-r3566.gz must be checked first... |
|
|
If it helps to check, I upload a text file with some details about the changes proposed in the patch Cheers |
|
2010-09-24 12:18
|
|
|
2010-10-01 16:22
|
|
|
2010-10-01 16:27
|
|
|
|
Hello, what is left of my changes to doc generation is uploaded in two patches, made against rev.3582 : one for KDL, the other for all other files. If you apply these two, the patch against rev. 3566 is obsolete. The five files in note 329 are still to be deleted. (edit) I did'nt knew to which Makefile.am I should add the files src/CXX/pycxx.dox and src/zipios++/zipios.dox in EXTRA_DIST list, so I leave it up to you. Don't hesitate to ask if you need smaller chunks to apply. Cheers Midgetfc |
|
|
OK, the patch for KDL has been applied and the files you mentioned have been removed from SVN. Most of the patch for the rest has been applied as it is but the issue with duplicate class names I used the @namespace tag from doxygen. Then there were a couple of things with src/Doc/CMakelists.txt which used the new command "file(COPY)" which is not available for cmake version older than 2.8. After all I have a couple of warnings left. These are: 1>C:/Projects/FreeCAD/x64-build/Doc/doxygen-headers/swigpyrun.h:326: Warning: include file string.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/swigpyrun_1.3.25.h:116: Warning: include file string.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/swigpyrun_1.3.33.h:323: Warning: include file string.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/swigpyrun_1.3.36.h:330: Warning: include file string.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/swigpyrun_1.3.38.h:326: Warning: include file string.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/swigpyrun_1.3.40.h:326: Warning: include file string.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/lex.UnitsApi.c:38: Warning: include file stdio.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/lex.UnitsApi.c:39: Warning: include file string.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/lex.UnitsApi.c:40: Warning: include file errno.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Base/lex.UnitsApi.c:41: Warning: include file stdlib.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Gui/lex.SelectionFilter.c:38: Warning: include file stdio.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Gui/lex.SelectionFilter.c:39: Warning: include file string.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Gui/lex.SelectionFilter.c:40: Warning: include file errno.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Gui/lex.SelectionFilter.c:41: Warning: include file stdlib.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Gui/lex.SelectionFilter.c:498: Warning: include file string not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Gui/lex.SelectionFilter.c:500: Warning: include file stdio.h not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Gui/SelectionView.cpp:71: warning: no uniquely matching class member found for 1> void SelectionView::OnChange(Base::Subject< const SelectionChanges & > &rCaller, Gui::SelectionChanges Reason) 1>Possible candidates: 1> virtual void Gui::DockWnd::SelectionView::OnChange(Gui::SelectionSingleton::SubjectType &rCaller, Gui::SelectionSingleton::MessageType Reason) at line 75 of file C:/Projects/FreeCAD/src/Gui/SelectionView.h 1>C:/Projects/FreeCAD/src/Mod/Mesh/App/WildMagic4/Wm4System.inl:33: warning: no matching file member found for 1>void Wm4::Deallocate(T **&raatArray)Possible candidates: 1> static void Deallocate(T **&raatArray) 1> void Deallocate(T ***&raaatArray) |
|
2010-10-04 12:34
|
|
|
|
Hello, fist of all, thanks for applying the patch. You will even totally suppress warnings ! I uploaded a slightly improved version for doxytips.dox I think that we will have now a clean basis to improve source documentation, and don't see it as an achievement but as a starting point. As I browse through it, I'll try to check for poorly formatted or documented parts, and propose patches if you are OK. Just out of curiosity, what is the reason for your dealing with duplicate names issue ? (with @namespace) I suppose i's not just a matter of taste. Is it related to some Python part of the code? Cheers Midgetfc |
|
|
After adding an exclude pattern for the SWIG and lex.*.c source files and ignoring all the OnChange() methods I have only these two warnings left: 1>C:/Projects/FreeCAD/src/Base/UnitsApi.cpp:229: Warning: include file lex.UnitsApi.c not found, perhaps you forgot to add its directory to INCLUDE_PATH? 1>C:/Projects/FreeCAD/src/Gui/SelectionFilter.cpp:143: Warning: include file lex.SelectionFilter.c not found, perhaps you forgot to add its directory to INCLUDE_PATH? This is because I have excluded lex.UnitsApi.c and lex.SelectionFilter.c. Is there a way to ignore #include statements in doxygen? |
|
|
> Just out of curiosity, what is the reason for your dealing with duplicate names issue ? (with @namespace) I suppose i's not just a matter of taste. Is it related to some Python part of the code? For the implementation of a class I always start with the line using namespace blah; because I don't like it to write all the time the whole namespace prefix for each class method. So, in the end this is my personal taste. Another point is that when e.g. preparing a new workbench class I usually copy/paste the code of an existing workbench class and then it would a bit annoying to always remove the namespace part. But I must admit there is no technical reason or so to have the namespace as prefix or not. |
|
|
I don't know. I'll try to find, but don't have time for it just now. By the way, the file(COPY) replacement in src/Doc/CMakeLists.txt doesn't seem to work as expected (FCConfig.h copied as doxygen-headers, and no directory created) Now that you indicated the way to go, I can tackle this. You really intend that, if necessary, the files are to be copied under CMAKE_BINARY_DIR ? |
|
|
OK, your last patch has been applied. So far thanks again for your great contribution. |
|
|
> Now that you indicated the way to go, I can tackle this. You really intend that, if necessary, the files are to be copied under CMAKE_BINARY_DIR ? Usually, when doing an out-of-source build the source directory shouldn't be touched, i.e. no files should be created there. > By the way, the file(COPY) replacement in src/Doc/CMakeLists.txt doesn't seem to work as expected (FCConfig.h copied as doxygen-headers, and no directory created) For me it works well. What actually is the reason to copy these three files? |
|
2010-10-04 20:55
|
|
|
|
>This is because I have excluded lex.UnitsApi.c and lex.SelectionFilter.c. Is >there a way to ignore #include statements in doxygen? Well, it sems the /// @cond DOXERR ... /// @endcond block does not work. I have not found a built-in way to coax doxygen to skip a header, so I propose to use an input filter, removing on the fly the offending lines. (FreecadDoxygenInputFilter.py) Please forgive me if if it is very crude, but I'm an absolute beginner in Python. The file is meant to be in src/Doc and to have execution rights. >For me it works well. What actually is the reason to copy these three files? On my system (debian squeeze), CMake command "copy" does not create directories if they don't exist. So, I added a line to create the directory for the additional include files For the 3 files, there was a little mess on my machine :( swigpyrun.h -> apologies. I had a stale copy of it in trunk directory. As this file is normally created in src/Base, it is already in the sources parsed by doxygen, no need to copy FCConfig.h -> omitting the defines it contains does not seem to bother doxygen, no need to copy SoSubField.h -> if doxygen has no access to this header, we have around 10 errors in src/Mod/Mesh/Gui/SoFCMeshFaceSet.cpp, src/Mod/Mesh/Gui/SoFCMeshObject.cpp and src/Mod/Mesh/Gui/SoFCMeshVertex.cpp, so this one is still needed. If I add its directory to INCLUDE_PATH of doxygen, I run into problems because it will parse recursively many subdirs. With just this file copied, it's fine. The patch joined has the input filter, an updated BuildDevDoc.cfg.in to use it and an updated CMakeLists.txt to correct the mess with copying header files. Edit: Now that things are more or less sorted out, I found a better way to deal with SoSubField.h. It must be parsed by Doxygen, but no need to copy it. Added in the sources list before the files where it is used is fine. doxygen-doc-patch-alt-r3605 proposes this. Apply the one you find more fit, but IMHO the alt is better. There are now 0 warnings left!!! :) Cheers Midgetfc |
|
2010-10-05 06:11
|
|
|
|
Applied the alt patch. The filter script is a nice idea but gives me more problems because the script cannot be started if .py files are not associated with the python executable. But using this as stated in the documentation works better than the @cond stuff #ifndef DOXYGEN_SHOULD_SKIP_THIS /* code that must be skipped by Doxygen */ #endif /* DOXYGEN_SHOULD_SKIP_THIS */ This makes the script obsolete now and is not that crude :) > There are now 0 warnings left!!! :) Yes, for me too now! :) |
|
|
Hello I was abused by the doc which states: "The new and easiest way is to add one comment block with a \cond command at the start and one comment block with a \endcond command at the end of the piece of code that should be ignored. This should be within the same file of course." Assumed that "new and easiest" meant "works better" ;( I keep my example of input filter at hand, in case we should need one someday. Is it windows specific that you can't easily launch a python script ? Would it work better with a C executable ? I still have much to learn towards portability, but I agree with you that it's of paramount importance :) In your opinion, what should next step be ? Maybe you could close this issue (after all, we reached a really "minimal" number of warnings) and we could let it rest a bit, some time to read through the generated doc and spot some remaining problems. By the way, you maybe already have some critics and/or remarks ? My own list is more a set of questions: There is some cleaning-up to do in src/Doc directory delete BuildDocDoxy.cfg,BuildDocDoxy.cfg.in,BuildDocDoxyFull.cfg ? Document.mm : isn't it obsolete ? what about BuildSourceDoc.bat : should we update ? Do you think it deserves a post in Feature Announcements on the forum ? Do you agree if we send a notice to dimitri@stack.nl to have FreeCAD added to the list of projects documented with doxygen once the new generated doc is online? What about the script fcbt.py and it's option BuildDoc ? should we update the script, the wiki pages which point to it, or both ? Anyway, is it possible to have editing rights on the wiki ? I would at minimum signal the "DevDoc" target on the pages pertaining to source documentation. I explored the possibilities given by parsing doxygen XML output, hoping to extract automatically some "up to date" statistics from the code for eg. feedback with the wiki. Nothing spectacular for now (eg. automatic list of freecad's commands) but it's why I wanted the best code coverage for the parser. Cheers Midgetfc |
|
|
Hello again, I've tested doc generation on a fresh checkout, with out of source CMake build, and discovered a new issue: By default FREECAD_BUILD_FEM is not set and Fem module is not built. Unfortunately, the conditional being in src/Mod/CMakeLists.txt, the whole subdir is not included in the build and its sources are not configured. Hence, generate_from_xml(FemMeshPy) is never called, FemMeshPy.h and FemMeshPy.cpp are not created and Doxygen chokes (10 wanings). I think we sould put the test for FREECAD_BUILD_FEM lower in the directories, to allow unconditional source configuration (at least generate all source files), but conditional compilation. We will run into the same problems in the future if we add python objects to Assembly and Cam modules later. Edit: It would be possible to add a switch on FREECAD_BUILD_FEM in the Doc/CMakeLists.txt but I would rather have a complete separation and choose independantly what is built in the app and what doc is generated. Gives freedom to later generate eg a "full" doc and some "trimmed out" doc sets for specific purposes or audiences (core Developper, module developper, power user, ...) |
|
|
> Is it windows specific that you can't easily launch a python script ? I think when installing an MSI package it does the association and probably adds the location of python.exe to the system path. But I built Python directly from sources and thus there is no association to the .py files. BTW, I rather prefer to start an editor when "executing" a .py file than calling the interpreter. So, at least on Windows you can't assume that invoking a Python script starts really the interpreter. > Would it work better with a C executable ? Maybe the line "python blah.py" works. But I haven't tested this. > delete BuildDocDoxy.cfg,BuildDocDoxy.cfg.in,BuildDocDoxyFull.cfg ? Yes, they're obsolete now and can be deleted for sure. > Document.mm : isn't it obsolete ? No idea what this file is. > what about BuildSourceDoc.bat : should we update ? Either updating or deleting > What about the script fcbt.py and it's option BuildDoc ? should we update the script, the wiki pages which point to it, or both ? I think we can really remove the BuildDoc target from here because we don't need dozens of ways to get the documentation built. > Do you think it deserves a post in Feature Announcements on the forum ? Sure, why not? > Do you agree if we send a notice to dimitri@stack.nl to have FreeCAD added to the list of projects documented with doxygen once the new generated doc is online? If you like you can send him a mail. > Anyway, is it possible to have editing rights on the wiki ? I would at minimum signal the "DevDoc" target on the pages pertaining to source documentation. Yes, I'll assign editing permission to you. |
|
|
> I think we sould put the test for FREECAD_BUILD_FEM lower in the directories If you find a way without too much work it would be OK. Otherwise we can also exclude the files from the documentation with DOXYGEN_SHOULD_SKIP_THIS because the C++ implementation of Python extensions is not really interesting for an application programmer. |
|
2010-10-07 19:11
|
|
|
2010-10-07 19:12
|
|
|
|
Hello, >if you find a way without too much work it would be OK. I found a way to preserve separation beetween code compilation and doc generation, hoping it satisfies your criteria. ;) The problem was threefold: - the source files for the python extensions are generated from xml at build time - which files are generated depends on the build options settings, at configuration time. - there is a configure dependency on smesh To solve the first, I modified slightly the macro generate_from_xml (in trunk/cMake/FreeCadMacros.cmake) adding a command to generate these files at least once at configuration time, and let afterwards the target set by "add_custom_command" do its work at build time if xml file is modified. To solve the second, I forced a reconfigure with all the required options set in DevDoc target before calling doxygen. I then cleanup by deleting cmake cache, resetting default options. We only have to set flags here if Assembly or Cam come to life later. As a side effect concerning working directory, I adjusted BuildDevDoc.cfg.in To avoid configure dependency on smeh, I modified src/Mod/Fem/App/CMakeLists.txt and src/Mod/Fem/Gui/CMakeLists.txt That's all (5 files touched). The dependencies may trigger double configure when building the docs, but that's not the most time consuming part. No warnings from doxygen again :) side notes on cMake/FreeCadMacros.cmake : it has not the proper mime type for SVN and is not included in the patch. To correct, either change property value (svn propset svn:mime-type text/plain src/Doc/CMakeLists.txt) or delete the property for this target, as text/plain is the default (svn propdel svn:mime-type src/Doc/CMakeLists.txt) in this file, the comment line 175 (# It would be a bit cleaner to generate these files in ${CMAKE_CURRENT_BINARY_DIR} ) seems obsolete if it applies to generate_from_xml in generate_from_xml macro, you set TOOL_PATH and SOURCE_PATH, but never use the latter. >...the C++ implementation of Python extensions is not really interesting for an application programmer. But it is a nice example for the curious ;) Cheers Midgetfc |
|
2010-10-08 05:29
|
|
|
|
>> What about the script fcbt.py and it's option BuildDoc ? should we update the script, the wiki pages which point to it, or both ? >I think we can really remove the BuildDoc target from here because we don't need dozens of ways to get the documentation built. Done in the proposed fcbt-patch-r3611 modified script src/Tools/fcbt.py modified file src/Tools/Makefile.am + todo on svn : remove src/Tools/fcbt/BuildDoc.py and src/Tools/fcbt/BuildDocDoxy.cfg I'll edit the wiki to reflect this change when it's applied. Cheers Midgetfc |
|
|
OK, all patches have been applied. But there is little problem with the change in FreeCADMacros.cmake because it touches the generated files all the time when you do a configure step. This is annoying because then all these files gets recompiled again. |
|
|
A check of whether the generated files exists or not solves this issue. |
|
2010-10-12 07:57
|
|
|
|
Hello, thanks for applying the patch. I've updated the wiki. One small correction in the patch against r3622 uploaded: the comment was seen pertaining to the boost namespace and not to the function. Will you update the online source doc when R11 is released ? Cheers Midgetfc |
|
|
Ok, applied. > Will you update the online source doc when R11 is released ? That should be up to Jürgen. |
|
|
Since the sources are doxygen clean now we can close this item. |
| Date Modified | Username | Field | Change |
|---|---|---|---|
| 2010-09-20 19:34 | midgetfc | New Issue | |
| 2010-09-20 19:34 | midgetfc | File Added: doxygen-doc-patch-r3566.gz | |
| 2010-09-21 18:26 | midgetfc | File Added: doxygen-doc-patch-r3568.gz | |
| 2010-09-21 18:27 | midgetfc | Note Added: 0000329 | |
| 2010-09-23 09:04 | midgetfc | Note Edited: 0000329 | |
| 2010-09-24 07:04 | wmayer | Note Added: 0000331 | |
| 2010-09-24 12:17 | midgetfc | Note Added: 0000332 | |
| 2010-09-24 12:18 | midgetfc | File Added: r3566patch-details.txt.gz | |
| 2010-10-01 16:22 | unauthenticated | File Added: doxygen-doc-patch-kdl-r3582.gz | |
| 2010-10-01 16:27 | midgetfc | File Added: doxygen-doc-patch-remains-r3582.gz | |
| 2010-10-01 16:35 | midgetfc | Note Added: 0000336 | |
| 2010-10-01 19:48 | midgetfc | Note Edited: 0000336 | |
| 2010-10-04 11:01 | wmayer | Note Added: 0000337 | |
| 2010-10-04 12:34 | midgetfc | File Added: doxygen-doc-patch-r3603.gz | |
| 2010-10-04 12:45 | midgetfc | Note Added: 0000338 | |
| 2010-10-04 12:48 | midgetfc | Note Edited: 0000338 | |
| 2010-10-04 12:52 | wmayer | Note Added: 0000339 | |
| 2010-10-04 13:08 | wmayer | Note Added: 0000340 | |
| 2010-10-04 13:09 | midgetfc | Note Added: 0000341 | |
| 2010-10-04 13:12 | wmayer | Note Added: 0000342 | |
| 2010-10-04 14:03 | wmayer | Note Added: 0000343 | |
| 2010-10-04 20:55 | midgetfc | File Added: doxygen-doc-patch-r3605.gz | |
| 2010-10-04 21:08 | midgetfc | Note Added: 0000344 | |
| 2010-10-05 06:11 | midgetfc | File Added: doxygen-doc-patch-alt-r3605.gz | |
| 2010-10-05 06:18 | midgetfc | Note Edited: 0000344 | |
| 2010-10-05 08:16 | wmayer | Note Added: 0000346 | |
| 2010-10-05 08:18 | wmayer | Assigned To | => wmayer |
| 2010-10-05 08:18 | wmayer | Status | new => assigned |
| 2010-10-05 11:00 | midgetfc | Note Added: 0000347 | |
| 2010-10-05 19:03 | midgetfc | Note Added: 0000350 | |
| 2010-10-05 19:14 | midgetfc | Note Edited: 0000350 | |
| 2010-10-06 08:15 | wmayer | Note Added: 0000351 | |
| 2010-10-06 08:26 | wmayer | Note Added: 0000352 | |
| 2010-10-07 19:11 | midgetfc | File Added: doxygen-doc-patch-r3610.gz | |
| 2010-10-07 19:12 | midgetfc | File Added: FreeCadMacros.cmake.gz | |
| 2010-10-07 19:19 | midgetfc | Note Added: 0000353 | |
| 2010-10-08 05:29 | midgetfc | File Added: fcbt-patch-r3611.gz | |
| 2010-10-08 05:34 | midgetfc | Note Added: 0000355 | |
| 2010-10-11 14:01 | wmayer | Note Added: 0000360 | |
| 2010-10-11 14:09 | wmayer | Note Added: 0000361 | |
| 2010-10-12 07:57 | midgetfc | File Added: doxygen-doc-patch-r3622.gz | |
| 2010-10-12 08:03 | midgetfc | Note Added: 0000369 | |
| 2010-10-12 09:45 | wmayer | Note Added: 0000371 | |
| 2010-10-13 09:36 | wmayer | Note Added: 0000375 | |
| 2010-10-13 09:36 | wmayer | Status | assigned => closed |
| 2010-10-13 09:36 | wmayer | Resolution | open => fixed |
