From 8870ffb0183e4a9ec2333021f46b430b0104ee0e Mon Sep 17 00:00:00 2001 From: Thomas Krijnen Date: Sat, 8 Aug 2026 03:44:56 +0200 Subject: [PATCH] Rework c++ docs --- .gitmodules | 3 -- cmake/CMakeLists.txt | 3 +- docs/cpp-api/CMakeLists.txt | 46 +++++------------ docs/cpp-api/Doxyfile | 85 +++++++++++++++++++++++--------- docs/cpp-api/README.md | 59 +++++++++++++++------- src/ifcgeom/ConversionSettings.h | 63 +++++++---------------- src/ifcgeom/GeometrySerializer.h | 17 ++----- src/ifcparse/file.h | 10 ++-- 8 files changed, 146 insertions(+), 140 deletions(-) diff --git a/.gitmodules b/.gitmodules index ac12797d0b..07e27d88a5 100644 --- a/.gitmodules +++ b/.gitmodules @@ -8,9 +8,6 @@ [submodule "src/ifcopenshell-python/test/Sample-BIM-Files"] path = src/ifcopenshell-python/test/Sample-BIM-Files url = https://github.com/IfcOpenShell/ids-test-files -[submodule "docs/cpp-api/assets/doxygen-awesome-css"] - path = docs/cpp-api/assets/doxygen-awesome-css - url = https://github.com/jothepro/doxygen-awesome-css.git [submodule "src/ifcopenshell-python/ifcopenshell/simple_spf"] path = src/ifcopenshell-python/ifcopenshell/simple_spf url = https://github.com/IfcOpenShell/step-file-parser diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index 0e5d7bc01f..e12030b876 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -693,8 +693,7 @@ endif() # Documentation if(BUILD_DOCUMENTATION) - set(CMAKE_MODULE_PATH "../docs/cmake") - add_subdirectory(../docs docs) + add_subdirectory(../docs/cpp-api docs/cpp-api) endif() if(BUILD_EXAMPLES) diff --git a/docs/cpp-api/CMakeLists.txt b/docs/cpp-api/CMakeLists.txt index 80593dd220..deab5f9eaa 100644 --- a/docs/cpp-api/CMakeLists.txt +++ b/docs/cpp-api/CMakeLists.txt @@ -1,35 +1,15 @@ -#Look for an executable called sphinx-build -find_program(SPHINX_EXECUTABLE NAMES sphinx-build DOC "Path to sphinx-build executable") - -include(FindPackageHandleStandardArgs) - -#Handle standard arguments to find_package like REQUIRED and QUIET -find_package_handle_standard_args(Sphinx "Failed to find sphinx-build executable" SPHINX_EXECUTABLE) - find_package(Doxygen REQUIRED) -#find_package(Sphinx REQUIRED) +find_program( + SPHINX_EXECUTABLE + NAMES sphinx-build + REQUIRED + DOC "Path to the sphinx-build executable" +) -set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}) -set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/docs/sphinx) - -message(STATUS "SPHINX BUILD ${CMAKE_CURRENT_BINARY_DIR}") - -file(MAKE_DIRECTORY ./output/doxygen) - -if(DOXYGEN_FOUND) - add_custom_target( - Sphinx - ALL - COMMAND ${SPHINX_EXECUTABLE} -v -T -b html ${SPHINX_SOURCE} ${CMAKE_CURRENT_SOURCE_DIR}/output - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/output - COMMENT "Generating documentation with Sphinx" - ) - - # add_custom_target(ifcopenshell_python_docs ALL - # COMMAND make html - # WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../src/ifcblenderexport/docs - # OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/../src/ifcblenderexport/docs - # COMMENT "Generating documentation with Sphinx") -else(DOXYGEN_FOUND) - message("Doxygen need to be installed to generate the doxygen documentation") -endif(DOXYGEN_FOUND) +add_custom_target( + cpp_api_docs + COMMAND ${SPHINX_EXECUTABLE} -M html . output -W --keep-going + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} + COMMENT "Generating the IfcOpenShell C++ API documentation" + VERBATIM +) diff --git a/docs/cpp-api/Doxyfile b/docs/cpp-api/Doxyfile index ac7452c780..9cda87ede0 100644 --- a/docs/cpp-api/Doxyfile +++ b/docs/cpp-api/Doxyfile @@ -68,7 +68,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = ./output +OUTPUT_DIRECTORY = ./output/doxygen # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format @@ -852,7 +852,7 @@ WARNINGS = YES # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as documenting some parameters in @@ -901,7 +901,7 @@ WARN_IF_UNDOC_ENUM_VAL = NO # Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. -WARN_AS_ERROR = NO +WARN_AS_ERROR = FAIL_ON_WARNINGS # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which @@ -944,7 +944,6 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = ../../src/ifcgeom \ - ../../src/ifcgeom_schema_agnostic \ ../../src/ifcparse \ ../../src/serializers \ @@ -1001,7 +1000,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +EXCLUDE = ../../src/ifcparse/schemas # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -1025,7 +1024,33 @@ EXCLUDE_PATTERNS = # wildcard * is used, a substring. Examples: ANamespace, AClass, # ANamespace::AClass, ANamespace::*Test -EXCLUDE_SYMBOLS = +EXCLUDE_SYMBOLS = "IfcGeom::OpaqueNumber::*" \ + "ifcopenshell::geometry::OpaqueNumber::*" \ + ifcopenshell::entity::attribute_by_name_cmp \ + ifcopenshell::impl::rocks_db_file_storage::rocksdb_types_iterator \ + ifcopenshell::impl::in_memory_file_storage::type_iterator \ + "util::string_buffer::*_item" \ + util::string_buffer::item \ + IfcGeom::layer_filter::wildcards_match \ + ifcopenshell::paged_file_impl::Entry \ + attribute_value::pointer_type \ + INCLUDE_PARENT_PARENT_DIR \ + POSTFIX_SCHEMA_ \ + POSTFIX_SCHEMA__ \ + STRINGIFY_ \ + MAKE_INIT_FN_ \ + MAKE_INIT_FN__ \ + key_from_string \ + add_ \ + subtract_ \ + multiply_ \ + divide_ \ + equals_ \ + less_than_ \ + negate_ \ + ifcopenshell::geometry::utils::create_cube \ + ifcopenshell::geometry::utils::create_polyhedron \ + ifcopenshell::geometry::utils::create_nef_polyhedron # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include @@ -1236,7 +1261,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = YES +GENERATE_HTML = NO # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1311,7 +1336,7 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = assets/doxygen-awesome-css/doxygen-awesome.css +HTML_EXTRA_STYLESHEET = # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -2166,7 +2191,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -2303,7 +2328,7 @@ ENABLE_PREPROCESSING = YES # The default value is: NO. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then # the macro expansion is limited to the macros specified with the PREDEFINED and @@ -2311,7 +2336,7 @@ MACRO_EXPANSION = NO # The default value is: NO. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -EXPAND_ONLY_PREDEF = NO +EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES, the include files in the # INCLUDE_PATH will be searched if a #include is found. @@ -2344,7 +2369,17 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = +PREDEFINED = IFC_PARSE_API= \ + IFC_SCHEMA_API= \ + IFC_GEOM_API= \ + IFC_GEOMLIBRARY_API= \ + IFC_GEOMSERIALIZATION_API= \ + SERIALIZERS_API= \ + "POSTFIX_SCHEMA(name)=name##_Schema" \ + "Handle(name):=opencascade::handle" \ + Kernel_=Kernel \ + SimpleKernel_=SimpleKernel \ + inline= # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -2353,7 +2388,22 @@ PREDEFINED = # definition found in the source code. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = Kernel_ \ + CgalShape \ + CgalKernel \ + cgal_placement_t \ + cgal_point_t \ + cgal_direction_t \ + cgal_vector_t \ + cgal_plane_t \ + cgal_curve_t \ + cgal_wire_t \ + cgal_face_t \ + cgal_shape_t \ + cgal_vertex_descriptor_t \ + cgal_face_descriptor_t \ + create_cube \ + create_polyhedron # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will # remove all references to function-like macros that are alone on a line, have @@ -2731,15 +2781,6 @@ DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) support -# this, this feature is disabled by default. -# The default value is: NO. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_MULTI_TARGETS = NO - # If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page # explaining the meaning of the various boxes and arrows in the dot generated # graphs. diff --git a/docs/cpp-api/README.md b/docs/cpp-api/README.md index dc08491250..73ac162626 100644 --- a/docs/cpp-api/README.md +++ b/docs/cpp-api/README.md @@ -1,33 +1,56 @@ # IfcOpenShell C++ API documentation -This folder contains the setup to build the IfcOpenShell C++ API documentation from the source code. +This directory contains the Sphinx, Doxygen, Breathe, and Exhale configuration +for the IfcOpenShell C++ API reference. During a Sphinx build, Exhale runs +Doxygen, Breathe consumes the generated XML, and Exhale creates the API pages. + +## Prerequisites + +- Python 3.10 or newer +- [Doxygen](https://www.doxygen.nl/) +- [Graphviz](https://graphviz.org/) + +Install the Python dependencies from this directory: + +```shell +python -m pip install -r requirements.txt +``` + +Both `doxygen` and `dot` must be available on `PATH`. For the standard Windows +install locations, this can be done for the current PowerShell session with: + +```powershell +$env:Path = "C:\Program Files\doxygen\bin;C:\Program Files\Graphviz\bin;$env:Path" +``` ## Generating the documentation -> Prerequisites: -> -> Make sure to have [Doxygen](https://www.doxygen.nl) and [Graphviz](https://graphviz.org) installed into your `$PATH` variable. -> -> The documentation also use the [doxygen-awesome](https://jothepro.github.io/doxygen-awesome-css) theme as a git submodule. - -Build with the command (from within the `/docs/cpp-api` folder): +From this directory, run: ```shell -$ doxygen +python -m sphinx -M html . output -W --keep-going ``` -To include the current git commit hash into the build documentation, use the following command: +To include the current Git commit in Doxygen's project metadata, set +`PROJECT_NUMBER` before building. For example, in PowerShell: + +```powershell +$env:PROJECT_NUMBER = git rev-parse --short HEAD +python -m sphinx -M html . output -W --keep-going +``` + +Or in a POSIX shell: ```shell -$ PROJECT_NUMBER=$(git rev-parse --short HEAD) doxygen +PROJECT_NUMBER=$(git rev-parse --short HEAD) python -m sphinx -M html . output -W --keep-going ``` -This will extract the current commit hash in short version and sets the propper ENV variable used by doxygen. +Alternatively, configure the main CMake project with +`-DBUILD_DOCUMENTATION=ON` and build the `cpp_api_docs` target. -The generation of the documentation might take a while depending on your systems hardware, as it is configured to generate the Class graphs using . +The generated documentation is written to `output/html/index.html`. The +generated Doxygen XML and Exhale sources are kept under `output/` as build +artifacts. -The resulting documentation is located unter `/cpp-api/output/html` and can be directly accessed with your browser: - -```shell -$ open ./output/html/index.html -``` +The generated headers under `src/ifcparse/schemas` are intentionally excluded +from this documentation build. diff --git a/src/ifcgeom/ConversionSettings.h b/src/ifcgeom/ConversionSettings.h index d7ade76343..6a6daf058a 100644 --- a/src/ifcgeom/ConversionSettings.h +++ b/src/ifcgeom/ConversionSettings.h @@ -117,10 +117,7 @@ namespace ifcopenshell { struct ReorientShells : public SettingBase { static constexpr const char* const name = "reorient-shells"; - static constexpr const char* const description = "Specifies whether to orient the faces of IfcConnectedFaceSets. " - "This is a potentially time consuming operation, but guarantees a " - "consistent orientation of surface normals, even if the faces are not " - "properly oriented in the IFC file."; + static constexpr const char* const description = "Specifies whether to orient the faces of IfcConnectedFaceSets. This is a potentially time consuming operation, but guarantees a consistent orientation of surface normals, even if the faces are not properly oriented in the IFC file."; static constexpr bool defaultvalue = false; }; @@ -144,15 +141,13 @@ namespace ifcopenshell { struct LayersetFirst : public SettingBase { static constexpr const char* const name = "layerset-first"; - static constexpr const char* const description = "Assigns the first layer material of the layerset " - "to the complete product."; + static constexpr const char* const description = "Assigns the first layer material of the layerset to the complete product."; static constexpr bool defaultvalue = false; }; struct DisableBooleanResult : public SettingBase { static constexpr const char* const name = "disable-boolean-result"; - static constexpr const char* const description = "Specifies whether to disable the boolean operation within representations " - "such as clippings by means of IfcBooleanResult and subtypes"; + static constexpr const char* const description = "Specifies whether to disable the boolean operation within representations such as clippings by means of IfcBooleanResult and subtypes"; static constexpr bool defaultvalue = false; }; @@ -170,9 +165,7 @@ namespace ifcopenshell { struct PrecisionFactor : public SettingBase { static constexpr const char* const name = "precision-factor"; - static constexpr const char* const description = "Option to increase linear tolerance for more permissive edge curves and fewer artifacts after " - "boolean operations at the expense of geometric detail " - "due to vertex collapsing and wire intersection fuzziness."; + static constexpr const char* const description = "Option to increase linear tolerance for more permissive edge curves and fewer artifacts after boolean operations at the expense of geometric detail due to vertex collapsing and wire intersection fuzziness."; static constexpr double defaultvalue = 1.0; }; @@ -192,41 +185,31 @@ namespace ifcopenshell { struct WeldVertices : public SettingBase { static constexpr const char* const name = "weld-vertices"; - static constexpr const char* const description = "Specifies whether vertices are welded, meaning that the coordinates " - "vector will only contain unique xyz-triplets. This results in a " - "manifold mesh which is useful for modelling applications, but might " - "result in unwanted shading artefacts in rendering applications."; + static constexpr const char* const description = "Specifies whether vertices are welded, meaning that the coordinates vector will only contain unique xyz-triplets. This results in a manifold mesh which is useful for modelling applications, but might result in unwanted shading artefacts in rendering applications."; static constexpr bool defaultvalue = true; }; struct UseWorldCoords : public SettingBase { static constexpr const char* const name = "use-world-coords"; - static constexpr const char* const description = "Specifies whether to apply the local placements of building elements " - "directly to the coordinates of the representation mesh rather than " - "to represent the local placement in the 4x3 matrix, which will in that " - "case be the identity matrix."; + static constexpr const char* const description = "Specifies whether to apply the local placements of building elements directly to the coordinates of the representation mesh rather than to represent the local placement in the 4x3 matrix, which will in that case be the identity matrix."; static constexpr bool defaultvalue = false; }; struct UnifyShapes : public SettingBase { static constexpr const char* const name = "unify-shapes"; - static constexpr const char* const description = "Unify adjacent co-planar and co-linear subshapes (topological entities " - "sharing the same geometric domain) before triangulation or further processing"; + static constexpr const char* const description = "Unify adjacent co-planar and co-linear subshapes (topological entities sharing the same geometric domain) before triangulation or further processing"; static constexpr bool defaultvalue = false; }; struct UseMaterialNames : public SettingBase { static constexpr const char* const name = "use-material-names"; - static constexpr const char* const description = "Use material names instead of unique IDs for naming materials upon serialization. " - "Applicable for OBJ and DAE output."; + static constexpr const char* const description = "Use material names instead of unique IDs for naming materials upon serialization. Applicable for OBJ and DAE output."; static constexpr bool defaultvalue = false; }; struct ConvertBackUnits : public SettingBase { static constexpr const char* const name = "convert-back-units"; - static constexpr const char* const description = "Specifies whether to convert back geometrical output back to the " - "unit of measure in which it is defined in the IFC file. Default is " - "to use meters."; + static constexpr const char* const description = "Specifies whether to convert back geometrical output back to the unit of measure in which it is defined in the IFC file. Default is to use meters."; static constexpr bool defaultvalue = false; }; @@ -260,10 +243,7 @@ namespace ifcopenshell { struct OutputDimensionality : public SettingBase { static constexpr const char* const name = "dimensionality"; - static constexpr const char* const description = - "Specifies whether to include curves and/or surfaces and solids in the output result. " - "Defaults to only surfaces and solids (SURFACES_AND_SOLIDS). " - "Other possible values are CURVES, CURVES_SURFACES_AND_SOLIDS."; + static constexpr const char* const description = "Specifies whether to include curves and/or surfaces and solids in the output result. Defaults to only surfaces and solids (SURFACES_AND_SOLIDS). Other possible values are CURVES, CURVES_SURFACES_AND_SOLIDS."; static constexpr OutputDimensionalityTypes defaultvalue = SURFACES_AND_SOLIDS; }; @@ -283,8 +263,7 @@ namespace ifcopenshell { struct DisableOpeningSubtractions : public SettingBase { static constexpr const char* const name = "disable-opening-subtractions"; - static constexpr const char* const description = "Specifies whether to disable the boolean subtraction of " - "IfcOpeningElement Representations from their RelatingElements."; + static constexpr const char* const description = "Specifies whether to disable the boolean subtraction of IfcOpeningElement Representations from their RelatingElements."; static constexpr bool defaultvalue = false; }; @@ -302,30 +281,25 @@ namespace ifcopenshell { struct DontEmitNormals : public SettingBase { static constexpr const char* const name = "no-normals"; - static constexpr const char* const description = "Disables computation of normals.Saves time and file size and is useful " - "in instances where you're going to recompute normals for the exported " - "model in other modelling application in any case."; + static constexpr const char* const description = "Disables computation of normals.Saves time and file size and is useful in instances where you're going to recompute normals for the exported model in other modelling application in any case."; static constexpr bool defaultvalue = false; }; struct GenerateUvs : public SettingBase { static constexpr const char* const name = "generate-uvs"; - static constexpr const char* const description = "Generates UVs (texture coordinates) by using simple box projection. Requires normals. " - "Not guaranteed to work properly if used with --weld-vertices."; + static constexpr const char* const description = "Generates UVs (texture coordinates) by using simple box projection. Requires normals. Not guaranteed to work properly if used with --weld-vertices."; static constexpr bool defaultvalue = false; }; struct ApplyLayerSets : public SettingBase { static constexpr const char* const name = "enable-layerset-slicing"; - static constexpr const char* const description = "Specifies whether to enable the slicing of products according " - "to their associated IfcMaterialLayerSet."; + static constexpr const char* const description = "Specifies whether to enable the slicing of products according to their associated IfcMaterialLayerSet."; static constexpr bool defaultvalue = false; }; struct UseElementHierarchy : public SettingBase { static constexpr const char* const name = "element-hierarchy"; - static constexpr const char* const description = "Assign the elements using their e.g IfcBuildingStorey parent." - "Applicable to DAE output."; + static constexpr const char* const description = "Assign the elements using their e.g IfcBuildingStorey parent.Applicable to DAE output."; static constexpr bool defaultvalue = false; }; @@ -343,8 +317,7 @@ namespace ifcopenshell { struct SiteLocalPlacement : public SettingBase { static constexpr const char* const name = "site-local-placement"; - static constexpr const char* const description = "Place elements locally in the IfcSite coordinate system, instead of placing " - "them in the IFC global coords. Applicable for OBJ, DAE, and STP output."; + static constexpr const char* const description = "Place elements locally in the IfcSite coordinate system, instead of placing them in the IFC global coords. Applicable for OBJ, DAE, and STP output."; static constexpr bool defaultvalue = false; }; @@ -421,9 +394,7 @@ namespace ifcopenshell { struct KeepBoundingBoxes : public SettingBase { static constexpr const char* const name = "keep-bounding-boxes"; - static constexpr const char* const description = - "Default is to removes IfcBoundingBox from model prior to converting geometry." - "Setting this option disables that behaviour"; + static constexpr const char* const description = "Default is to removes IfcBoundingBox from model prior to converting geometry.Setting this option disables that behaviour"; static constexpr bool defaultvalue = false; }; diff --git a/src/ifcgeom/GeometrySerializer.h b/src/ifcgeom/GeometrySerializer.h index 0d880f5a5c..25de78f3af 100644 --- a/src/ifcgeom/GeometrySerializer.h +++ b/src/ifcgeom/GeometrySerializer.h @@ -31,29 +31,25 @@ inline namespace settings { struct UseElementNames : public SettingBase { static constexpr const char* const name = "use-element-names"; - static constexpr const char* const description = "Use entity instance IfcRoot.Name instead of unique IDs for naming elements upon serialization. " - "Applicable for OBJ, DAE, STP, and SVG output."; + static constexpr const char* const description = "Use entity instance IfcRoot.Name instead of unique IDs for naming elements upon serialization. Applicable for OBJ, DAE, STP, and SVG output."; static constexpr bool defaultvalue = false; }; struct UseElementGuids : public SettingBase { static constexpr const char* const name = "use-element-guids"; - static constexpr const char* const description = "Use entity instance IfcRoot.GlobalId instead of unique IDs for naming elements upon serialization. " - "Applicable for OBJ, DAE, STP, and SVG output."; + static constexpr const char* const description = "Use entity instance IfcRoot.GlobalId instead of unique IDs for naming elements upon serialization. Applicable for OBJ, DAE, STP, and SVG output."; static constexpr bool defaultvalue = false; }; struct UseElementStepIds : public SettingBase { static constexpr const char* const name = "use-element-step-ids"; - static constexpr const char* const description = "Use the numeric step identifier (entity instance name) for naming elements upon serialization. " - "Applicable for OBJ, DAE, STP, and SVG output."; + static constexpr const char* const description = "Use the numeric step identifier (entity instance name) for naming elements upon serialization. Applicable for OBJ, DAE, STP, and SVG output."; static constexpr bool defaultvalue = false; }; struct UseElementTypes : public SettingBase { static constexpr const char* const name = "use-element-types"; - static constexpr const char* const description = "Use element types instead of unique IDs for naming elements upon serialization. " - "Applicable to DAE output."; + static constexpr const char* const description = "Use element types instead of unique IDs for naming elements upon serialization. Applicable to DAE output."; static constexpr bool defaultvalue = false; }; @@ -71,10 +67,7 @@ inline namespace settings { struct FloatingPointDigits : public SettingBase { static constexpr const char* const name = "digits"; - static constexpr const char* const description = "Sets the precision to be used to format floating-point values, 15 by default. " - "Use a negative value to use the system's default precision (should be 6 typically). " - "Applicable for OBJ and DAE output. For DAE output, value >= 15 means that up to 16 decimals are used, " - " and any other value means that 6 or 7 decimals are used."; + static constexpr const char* const description = "Sets the precision to be used to format floating-point values, 15 by default. Use a negative value to use the system's default precision (should be 6 typically). Applicable for OBJ and DAE output. For DAE output, value >= 15 means that up to 16 decimals are used, and any other value means that 6 or 7 decimals are used."; static constexpr int defaultvalue = 15; }; diff --git a/src/ifcparse/file.h b/src/ifcparse/file.h index f40999f643..a610c1f60c 100644 --- a/src/ifcparse/file.h +++ b/src/ifcparse/file.h @@ -247,8 +247,9 @@ public: /// Constructs an file object from a file path, supports IFC-SPF and the IfcOpenShell-specific RocksDB format. /// /// UTF-8 file path to an IFC-SPF file or RocksDB database directory - /// File type of the path - /// Whether to open in read-only mode, only supported on RocksDB databases + /// File type of the path + /// Whether to open in read-only mode, only supported on RocksDB databases + /// Logger used while opening the file file(const std::string& path, filetype type = FT_AUTODETECT, bool read_only = false, ::logger& logger = ::logger::root()); /// @@ -263,11 +264,12 @@ public: /// /// Constructs an file object with the specified schema, file type, and file path. - /// @nb path is only used in rocksdb mode, for spf file is in-memory only until write() is called + /// @note path is only used in RocksDB mode; an SPF file is in memory only until write() is called. /// /// Pointer to the schema definition to use. Defaults to the IFC4 schema if not specified. - /// The file type to use for the file. Defaults to FT_AUTODETECT. + /// The file type to use for the file. Defaults to FT_AUTODETECT. /// The file system path to the IFC file. Defaults to an empty string. + /// Logger used while creating the file. file(const ifcopenshell::schema_definition* schema = ifcopenshell::schema_by_name("IFC4"), filetype type = FT_AUTODETECT, const std::string& path = "", ::logger& logger = ::logger::root()); ///