cloudViewer::docstring::FunctionDoc Class Reference

#include <docstring.h>

Collaboration diagram for cloudViewer::docstring::FunctionDoc:

Classes
struct	OverloadDocs

Public Member Functions
	FunctionDoc (const std::string &pybind_doc)
std::string	ToGoogleDocString () const
	Generate Google style python docstring. More...

Public Attributes
std::string	name_ = ""
std::string	preamble_ = ""
std::vector< OverloadDocs >	overload_docs_

Protected Member Functions
size_t	ParseFunctionName ()
size_t	ParseSummary ()
void	ParseArguments ()
	Parse ArgumentDoc for each argument. More...
void	ParseReturn ()
	Parse function return. More...

Static Protected Member Functions
static std::vector< std::string >	GetArgumentTokens (const std::string &pybind_doc)
static ArgumentDoc	ParseArgumentToken (const std::string &argument_token)
	Parse individual argument token and returns a ArgumentDoc. More...
static std::string	StringCleanAll (std::string &s, const std::string &white_space=" \t\n")
	Runs all string cleanup functions. More...

Protected Attributes
std::string	pybind_doc_ = ""
size_t	doc_pos_ [2] = {0, std::string::npos}

Detailed Description

This class is designed to parse docstrings generated by pybind11 and convert to Python friendly Google-style docstring with the flexibility of adding additional docstrings manually.

The automated part includes:

1. Function name
2. Argument
   • Name
   • Type
   • Default value
3. Return type
4. Brief "summary" docstring received from pybind Optionally, the user can inject additional docstrings to the class.

This approach was chosen in favor of writting docstring in Python files for two reasons 1) We don't need to create additional (pure) Python wrapper functions, 2) The type information generated by pybind is preserved.

However, this also comes with a drawback: FunctionDoc rely on docstrings generated by pybind11, which is subject to change. So if a new version of pybind11 changes the format of docstring, this class needs to be updated accordingly. Another alternative approach is to modify pybind11 directly, although it makes some of the parsing part simpler, it could be much harder to maintain to keep track of the upstream pybind11.

Example usage:

std::string doc = R"(foo(arg0: int, arg1: float = 1.0) -> cloudViewer.bar)";
FunctionDoc fd(doc);
fd.InjectArgumentDocBody("arg0", "The arg0 is an important argument.");
std::cout << fd.ToGoogleDocString();

Definition at line 62 of file docstring.h.

Constructor & Destructor Documentation

FunctionDoc()

cloudViewer::docstring::FunctionDoc::FunctionDoc

(

const std::string &

pybind_doc

)

Definition at line 106 of file docstring.cpp.

References doc_pos_, ParseArguments(), ParseFunctionName(), ParseReturn(), and ParseSummary().

Member Function Documentation

GetArgumentTokens()

std::vector< std::string > cloudViewer::docstring::FunctionDoc::GetArgumentTokens ( const std::string &  pybind_doc )

staticprotected

Split docstring to argument tokens. E.g. "cylinder_radius: float = 1.0", "cylinder_radius: float"

Definition at line 329 of file docstring.cpp.

Referenced by ParseArguments().

ParseArguments()

void cloudViewer::docstring::FunctionDoc::ParseArguments ( )

protected

Parse ArgumentDoc for each argument.

Definition at line 160 of file docstring.cpp.

References doc_pos_, GetArgumentTokens(), overload_docs_, ParseArgumentToken(), and pybind_doc_.

Referenced by FunctionDoc().

ParseArgumentToken()

ArgumentDoc cloudViewer::docstring::FunctionDoc::ParseArgumentToken ( const std::string &  argument_token )

staticprotected

Parse individual argument token and returns a ArgumentDoc.

Definition at line 290 of file docstring.cpp.

References cloudViewer::docstring::ArgumentDoc::default_, cloudViewer::docstring::ArgumentDoc::long_default_, cloudViewer::docstring::ArgumentDoc::name_, and cloudViewer::docstring::ArgumentDoc::type_.

Referenced by ParseArguments().

ParseFunctionName()

size_t cloudViewer::docstring::FunctionDoc::ParseFunctionName ( )

protected

Parse the function name from docstring.

Returns

Position in docstring after the name or after the string "Overloaded function.", if it exists.

Definition at line 118 of file docstring.cpp.

References name, name_, preamble_, and pybind_doc_.

Referenced by FunctionDoc().

ParseReturn()

void cloudViewer::docstring::FunctionDoc::ParseReturn ( )

protected

Parse function return.

Definition at line 175 of file docstring.cpp.

References doc_pos_, overload_docs_, pybind_doc_, StringCleanAll(), and cloudViewer::utility::WordLength().

Referenced by FunctionDoc().

ParseSummary()

size_t cloudViewer::docstring::FunctionDoc::ParseSummary ( )

protected

Parse the function "summary" docstring received from pybind.

Returns

Position in docstring at the end of the summary. Used to set limits for parsing the current overload.

Definition at line 134 of file docstring.cpp.

References doc_pos_, name_, overload_docs_, pybind_doc_, StringCleanAll(), and cloudViewer::utility::WordLength().

Referenced by FunctionDoc().

StringCleanAll()

std::string cloudViewer::docstring::FunctionDoc::StringCleanAll ( std::string &  s, const std::string &  white_space = " \t\n"  )

staticprotected

Runs all string cleanup functions.

Definition at line 284 of file docstring.cpp.

References cloudViewer::utility::StripString().

Referenced by ParseReturn(), ParseSummary(), and ToGoogleDocString().

ToGoogleDocString()

std::string cloudViewer::docstring::FunctionDoc::ToGoogleDocString

(

)

const

Generate Google style python docstring.

Definition at line 187 of file docstring.cpp.

References cloudViewer::docstring::ArgumentDoc::body_, cloudViewer::docstring::ArgumentDoc::default_, QtCompat::endl(), cloudViewer::docstring::ArgumentDoc::long_default_, cloudViewer::docstring::ArgumentDoc::name_, name_, overload_docs_, preamble_, cloudViewer::utility::SplitString(), StringCleanAll(), and cloudViewer::docstring::ArgumentDoc::type_.

Referenced by cloudViewer::docstring::ClassMethodDocInject(), and cloudViewer::docstring::FunctionDocInject().

Member Data Documentation

doc_pos_

size_t cloudViewer::docstring::FunctionDoc::doc_pos_[2] = {0, std::string::npos}

protected

Definition at line 112 of file docstring.h.

Referenced by FunctionDoc(), ParseArguments(), ParseReturn(), and ParseSummary().

name_

std::string cloudViewer::docstring::FunctionDoc::name_ = ""

Definition at line 106 of file docstring.h.

Referenced by ParseFunctionName(), ParseSummary(), and ToGoogleDocString().

overload_docs_

std::vector<OverloadDocs> cloudViewer::docstring::FunctionDoc::overload_docs_

Definition at line 108 of file docstring.h.

Referenced by cloudViewer::docstring::ClassMethodDocInject(), cloudViewer::docstring::FunctionDocInject(), ParseArguments(), ParseReturn(), ParseSummary(), and ToGoogleDocString().

preamble_

std::string cloudViewer::docstring::FunctionDoc::preamble_ = ""

Definition at line 107 of file docstring.h.

Referenced by ParseFunctionName(), and ToGoogleDocString().

pybind_doc_

std::string cloudViewer::docstring::FunctionDoc::pybind_doc_ = ""

protected

Definition at line 111 of file docstring.h.

Referenced by ParseArguments(), ParseFunctionName(), ParseReturn(), and ParseSummary().

---

The documentation for this class was generated from the following files:

• /root/ACloudViewer/libs/Python/pybind/docstring.h
• /root/ACloudViewer/libs/Python/pybind/docstring.cpp