Merge pull request #17 from Tolc-Software/docs

Docs

Author: srydell

CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.15)
 
 project(
   Frontend.py
-  VERSION 0.4.1
+  VERSION 0.5.0
   LANGUAGES CXX)
 
 configure_file(docs/ReleaseNotes/version.in
@@ -37,23 +37,21 @@ include(FetchContent)
 FetchContent_Declare(
   IRSpecification
   GIT_REPOSITORY https://github.com/Tolc-Software/IntermediateRepresentation.git
-  GIT_TAG v0.11.0)
+  GIT_TAG v0.12.0)
 
 FetchContent_MakeAvailable(IRSpecification)
 
 add_library(
   Frontend.py
+  src/Frontend/Python/frontend.cpp
   src/Pybind/Builders/attributeBuilder.cpp
   src/Pybind/Builders/classBuilder.cpp
   src/Pybind/Builders/enumBuilder.cpp
   src/Pybind/Builders/functionBuilder.cpp
   src/Pybind/Builders/moduleBuilder.cpp
   src/Pybind/Builders/moduleFileBuilder.cpp
   src/Pybind/Builders/typeToStringBuilder.cpp
-  src/Frontend/Python/frontend.cpp
-  src/Pybind/checkType.cpp
-  src/Pybind/returnValuePolicy.cpp
-  src/Pybind/getOverloadedFunctions.cpp
+  src/Pybind/Helpers/getDocumentationParameter.cpp
   src/Pybind/Helpers/split.cpp
   src/Pybind/Helpers/string.cpp
   src/Pybind/Helpers/types.cpp
@@ -62,7 +60,10 @@ add_library(
   src/Pybind/Proxy/enum.cpp
   src/Pybind/Proxy/function.cpp
   src/Pybind/Proxy/module.cpp
-  src/Pybind/Proxy/moduleFile.cpp)
+  src/Pybind/Proxy/moduleFile.cpp
+  src/Pybind/checkType.cpp
+  src/Pybind/getOverloadedFunctions.cpp
+  src/Pybind/returnValuePolicy.cpp)
 
 add_warnings(TARGET Frontend.py)
 add_options(TARGET Frontend.py)

docs/ReleaseNotes/v0.5.0.md

@@ -0,0 +1,57 @@
+# News #
+
+## Bindings ##
+
+* Add support for transferring documentation from the C++ to pybind11
+  * Add tests for all officially supported documentation styles
+  * Supported for:
+    * Classes
+    * Member variables
+    * Enums
+    * Functions
+
+Example of documentation string styles:
+
+```cpp
+// One line comment
+class OneLiner {};
+
+/** Single multi line comment */
+class SingleMulti {};
+
+/**
+* Multi
+* line
+* comment
+*/
+class Multi {};
+
+/**
+Bare multi
+Another line
+*/
+class BareMulti {};
+
+/*!
+* Qt style
+*/
+class QtStyle {};
+
+/*******************************************************************************
+* JavaDoc Style
+* is
+* boxy
+******************************************************************************/
+class JavaDoc {};
+
+///
+/// Triplets is a commitment
+///
+class Triplets {};
+
+//!
+//! This is one of the doxy styles
+//!
+class DoxyBang {};
+```
+

docs/public/examples.md

@@ -36,6 +36,9 @@ public:
 
 	static int const i = 5;
 
+	// This class has a readwrite variable
+	int readwrite = 10;
+
 	std::string getS() { return m_s; }
 	std::string_view getSView() { return m_s; }
 
@@ -66,6 +69,15 @@ namespace MyLib {
 	};
 }
 
+/** Documentation carries over */
+struct Documentation {};
+
+/***********************************************************
+* JavaDoc Style
+* is
+* boxy
+**********************************************************/
+struct JavaDoc {};
 
 ```
 
@@ -79,6 +91,9 @@ self.assertEqual(m.WithConstructor.i, 5)
 with_constructor = m.WithConstructor("Hello")
 self.assertEqual(with_constructor.getS(), "Hello")
 
+# Documentation for variables carries over aswell
+self.assertIn("This class has a readwrite variable", m.WithConstructor.readwrite.__doc__)
+
 # Named arguments in constructors
 with_constructor = m.WithConstructor(s="named argument")
 self.assertEqual(with_constructor.getS(), "named argument")
@@ -105,6 +120,87 @@ self.assertEqual(
 nested = m.MyLib.Nested()
 self.assertEqual(nested.divideByTwo(10), 5)
 
+# Different styles of documentation on classes carries over
+self.assertIn("Documentation carries over", m.Documentation.__doc__)
+self.assertIn("JavaDoc Style", m.JavaDoc.__doc__)
+
+
+```
+
+
+## Documentation Styles ##
+
+
+```cpp
+
+// One line comment
+class OneLiner {};
+
+/** Single multi line comment */
+class SingleMulti {};
+
+/**
+* Multi
+* line
+* comment
+*/
+class Multi {};
+
+/**
+Bare multi
+Another line
+*/
+class BareMulti {};
+
+/*!
+* Qt style
+*/
+class QtStyle {};
+
+/*****************************
+* JavaDoc Style
+* is
+* boxy
+****************************/
+class JavaDoc {};
+
+///
+/// Triplets is a commitment
+///
+class Triplets {};
+
+//!
+//! This is one of the doxy styles
+//!
+class DoxyBang {};
+
+```
+
+
+```python
+
+# These types of documentations are supported for:
+#   Classes
+#   Member variables
+#   Enums
+#   Functions
+
+self.assertIn("One line comment", m.OneLiner.__doc__)
+
+self.assertIn("Single multi line", m.SingleMulti.__doc__)
+
+self.assertIn("Multi", m.Multi.__doc__)
+
+self.assertIn("Bare multi", m.BareMulti.__doc__)
+
+self.assertIn("Qt style", m.QtStyle.__doc__)
+
+self.assertIn("JavaDoc Style", m.JavaDoc.__doc__)
+
+self.assertIn("Triplets", m.Triplets.__doc__)
+
+self.assertIn("one of the doxy styles", m.DoxyBang.__doc__)
+
 ```
 
 
@@ -135,6 +231,7 @@ Unscoped f(Unscoped u) {
 }
 
 namespace NS {
+	// Documentation describing the enum
 	enum class Deep {
 		Double,
 		Down,
@@ -161,6 +258,9 @@ self.assertEqual(u, unscoped)
 deep = m.NS.Deep.Down
 self.assertNotEqual(deep, m.NS.Deep.Double)
 
+# Documentation carries over from C++
+self.assertIn("Documentation describing the enum", m.NS.Deep.__doc__)
+
 ```
 
 
@@ -184,10 +284,14 @@ void addYourOwn(std::string content) {
 	f.close();
 }
 
+/**
+* Documentation carries over
+*/
 int calculate() {
 	return 5;
 }
 
+// Different documentation styles are supported
 int missingArgumentsNaming(int, int i) {
 	return i;
 }
@@ -216,10 +320,13 @@ with open("hello.txt", "r") as f:
 
 result = m.calculate()
 self.assertEqual(result, 5)
+self.assertIn("Documentation carries over", m.calculate.__doc__)
 
 # Without naming variables is fine
 result = m.missingArgumentsNaming(2, 5)
 self.assertEqual(result, 5)
+self.assertIn("Different documentation styles are supported", \
+  m.missingArgumentsNaming.__doc__)
 
 # Not possible to name any variables unless they are all known
 with self.assertRaises(TypeError) as error_context:

src/Pybind/Builders/classBuilder.cpp

@@ -37,6 +37,7 @@ buildClass(IR::Struct const& cppClass, Pybind::Proxy::TypeInfo& typeInfo) {
 	        getTemplateParameterString(cppClass.m_templateArguments),
 	    cppClass.m_representation);
 
+	pyClass.setDocumentation(cppClass.m_documentation);
 	auto overloadedFunctions =
 	    Pybind::getOverloadedFunctions(cppClass.m_public.m_functions);
 	// Ignore private functions
@@ -79,6 +80,7 @@ buildClass(IR::Struct const& cppClass, Pybind::Proxy::TypeInfo& typeInfo) {
 	for (auto const& variable : cppClass.m_public.m_memberVariables) {
 		Pybind::checkType(variable.m_type, typeInfo);
 		pyClass.addMemberVariable(variable.m_name,
+		                          variable.m_documentation,
 		                          variable.m_type.m_isConst,
 		                          variable.m_type.m_isStatic);
 	}

src/Pybind/Builders/enumBuilder.cpp

@@ -7,6 +7,7 @@ Pybind::Proxy::Enum buildEnum(IR::Enum const& e) {
 	Pybind::Proxy::Enum proxyEnum(e.m_name, e.m_representation);
 
 	proxyEnum.setScoped(e.m_isScoped);
+	proxyEnum.setDocumentation(e.m_documentation);
 
 	for (auto const& value : e.m_values) {
 		proxyEnum.addValue(value);

src/Pybind/Builders/functionBuilder.cpp

@@ -15,8 +15,6 @@ buildFunction(IR::Function const& cppFunction,
 	    Pybind::Helpers::removeCppTemplate(cppFunction.m_name),
 	    cppFunction.m_representation);
 
-	std::set<std::string> includes;
-
 	for (auto const& arg : cppFunction.m_arguments) {
 		if (!Pybind::Helpers::isContainerType(arg.m_type,
 		                                      IR::ContainerType::UniquePtr)) {
@@ -33,6 +31,7 @@ buildFunction(IR::Function const& cppFunction,
 
 	Pybind::checkType(cppFunction.m_returnType, typeInfo);
 	pyFunction.setReturnType(cppFunction.m_returnType.m_representation);
+	pyFunction.setDocumentation(cppFunction.m_documentation);
 
 	if (cppFunction.m_returnType.m_numPointers > 0) {
 		pyFunction.setReturnValuePolicy(

src/Pybind/Helpers/getDocumentationParameter.cpp

@@ -0,0 +1,11 @@
+#include "Pybind/Helpers/getDocumentationParameter.hpp"
+#include <string>
+#include <fmt/format.h>
+
+namespace Pybind::Helpers {
+	std::string getDocumentationParameter(std::string const& documentation) {
+	    return documentation.empty() ?
+	               "\"\"" :
+                   fmt::format("R\"_tolc_docs({})_tolc_docs\"", documentation);
+    }
+}

src/Pybind/Helpers/getDocumentationParameter.hpp

@@ -0,0 +1,11 @@
+#pragma once
+#include <string>
+
+namespace Pybind::Helpers {
+/**
+* Return a valid parameter to pass to the creation of a pybind11 function
+* E.g.
+*   m.def("f", &f, {getDocumentationParameter('My function')})
+*/
+std::string getDocumentationParameter(std::string const& documentation);
+}