jessevdk / cldoc Goto Github PK
View Code? Open in Web Editor NEWclang based documentation generator for C and C++
License: GNU General Public License v2.0
clang based documentation generator for C and C++
License: GNU General Public License v2.0
E.g.
namespace foo
{
// A very useful function
template<class T>
void bar();
}
results in
Traceback (most recent call last):
File "/usr/bin/cldoc", line 5, in <module>
pkg_resources.run_script('cldoc==1.2', 'cldoc')
File "/usr/lib/python2.7/site-packages/distribute-0.6.24-py2.7.egg/pkg_resources.py", line 499, in run_script
self.require(requires)[0].run_script(script_name, ns)
File "/usr/lib/python2.7/site-packages/distribute-0.6.24-py2.7.egg/pkg_resources.py", line 1235, in run_script
execfile(script_filename, namespace, namespace)
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/EGG-INFO/scripts/cldoc", line 5, in <module>
cldoc.run()
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/__init__.py", line 152, in run
generate(opts, cxxflags)
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/__init__.py", line 30, in generate
generator.generate(os.path.join(opts.output, 'xml'))
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/generators/xml.py", line 49, in generate
Generator.generate(self, outdir)
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/generators/generator.py", line 22, in generate
self.generate_node(node)
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/generators/xml.py", line 471, in generate_node
self.generate_page(node)
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/generators/xml.py", line 438, in generate_page
elem = self.node_to_xml(node)
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/generators/xml.py", line 431, in node_to_xml
chelem = self.node_to_xml(child)
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/generators/xml.py", line 422, in node_to_xml
self.call_type_specific(node, elem, 'to_xml')
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/generators/xml.py", line 403, in call_type_specific
getattr(self, nm)(node, elem)
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/generators/xml.py", line 239, in method_to_xml
if len(node.override) > 0:
File "/usr/lib/python2.7/site-packages/cldoc-1.2-py2.7.egg/cldoc/nodes/method.py", line 37, in override
bases = list(self.parent.bases)
AttributeError: 'Namespace' object has no attribute 'bases'
cldoc works fine in most of the time.
But I meet this error when it processing a specific file which contains many macors.
The whole traceback is as following:
Traceback (most recent call last):
File "/usr/local/bin/cldoc", line 5, in <module>
cldoc.run()
File "/usr/local/lib/python2.7/dist-packages/cldoc/__init__.py", line 169, in run
generate(opts, cxxflags)
File "/usr/local/lib/python2.7/dist-packages/cldoc/__init__.py", line 44, in generate
generator.generate(os.path.join(opts.output, 'xml'))
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/xml.py", line 49, in generate
Generator.generate(self, outdir)
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/generator.py", line 22, in generate
self.generate_node(node)
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/xml.py", line 477, in generate_node
Generator.generate_node(self, node)
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/generator.py", line 27, in generate_node
self.generate_node(child)
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/xml.py", line 471, in generate_node
self.generate_page(node)
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/xml.py", line 438, in generate_page
elem = self.node_to_xml(node)
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/xml.py", line 431, in node_to_xml
chelem = self.node_to_xml(child)
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/xml.py", line 422, in node_to_xml
self.call_type_specific(node, elem, 'to_xml')
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/xml.py", line 403, in call_type_specific
getattr(self, nm)(node, elem)
File "/usr/local/lib/python2.7/dist-packages/cldoc/generators/xml.py", line 181, in type_to_xml
if tp.is_array:
File "/usr/local/lib/python2.7/dist-packages/cldoc/nodes/ctype.py", line 61, in is_array
return self.tp.kind == cindex.TypeKind.CONSTANTARRAY
AttributeError: 'TemplateType' object has no attribute 'tp'
Thanks,
Kyle
CMake can generate a compilation data-base for all files in a project (which includes per file compiler flags) as follows:
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
It would be awesome if cldoc could use it to generate documentation without needing to provide it with a list of files and flags.
Given:
namespace test {
struct foo {};
bool operator==(const foo &a, const foo &b);
}
This results in:
<function id="operator<" name="operator<">...</function>
Here, the operator does not have a namespace scope (presumably related to issue #43).
A typedef return type is taking precedence over the first parameter for selecting the type to associate a function with in the generated documentation.
The following code demonstrates the issue. The documentation for func_one and func_two is placed under err_t instead of bar_t.
typedef int err_t;
typedef struct _bar_t bar_t;
err_t func_one(bar_t *bar);
err_t func_two(bar_t *bar);
There is a current limitation in libclang which does not allow for retrieval of the return type of template functions/methods. This means that they are missing from the documentation as well.
Template classes are not shown on the index page, but appear on the namespace page. Further, there is no indication what so ever that it is a template class. The template arguments simply don't show up anywhere and there does not appear to be a mechanism for documenting them.
I'm getting the following error from cldoc when adding the --static
flag:
[dev@ubuntu:/tools/spifftools_ast (develop)] $ make doc
cldoc generate -std=c++11 -Wall -O0 -ggdb -fPIC -I include -I ../spifftools_utils/include -- --output docs --static src/./spifftools_ast_atribute.cpp src/./spifftools_ast.cpp src/./spifftools_ast_iterator.cpp src/./spifftools_ast_node.cpp src/./spifftools_ast_node_type.cpp src/./spiff_tools_asts.cpp src/./spifftools_ast_serializer.cpp src/./spifftools_asts_loader.cpp include/*.h
Processing `spifftools_ast_atribute.cpp'
Processing `spifftools_ast.cpp'
Processing `spifftools_ast_iterator.cpp'
Processing `spifftools_ast_node.cpp'
Processing `spifftools_ast_node_type.cpp'
Processing `spiff_tools_asts.cpp'
Processing `spifftools_ast_serializer.cpp'
Processing `spifftools_asts_loader.cpp'
Processing `ast_node_id_not_unique_exception.h'
Processing `key_not_found_exception.h'
Processing `source_location.h'
Processing `source_range.h'
Processing `spifftools_ast.h'
Processing `spifftools_ast_attribute.h'
Processing `spifftools_ast_iterator.h'
Processing `spifftools_ast_node.h'
Processing `spifftools_ast_node_type.h'
Processing `spifftools_ast_serializer.h'
Processing `spifftools_asts.h'
Processing `spifftools_asts_loader.h'
Generated `/tmp/tmpuu6zPv/xml'
Generated `/tmp/tmpuu6zPv/index.html'
Generating static website...
Failed to call static site generator. The static site generator uses node.js (http://nodejs.org/). Please make sure you have node installed on your system and try again.
make: *** [doc] Error 1
However, I have node.js installed on my machine:
[dev@ubuntu:/tools/spifftools_ast (develop)] $ which nodejs
/usr/bin/nodejs
[dev@ubuntu:/tools/spifftools_ast (develop)] $ nodejs --version
v0.6.19
Any ideas what I'm doing wrong?
If I delete the default copy constructor and assignment operator with C++11 syntax
Type (const Type &)=delete;
and Type &operator=(const Type &)=delete
then cldoc generates documentation stubs for the functions as if they were present and did something interesting. Without the mentioned declarations they disappear from the documentation as they should.
A workaround is to handle the deletions using a macro, much like DISALLOW_COPY_AND_ASSIGN in Google's C++ style guide. Then cldoc can be run with something like -DCLDOC and such macros #ifdef'd away.
Given:
enum class Color { Red, Green, Blue };
and associated documentation like:
#<cldoc:Color>
Describes a system color.
These colors are assocated with CSS-style `RGB` values of the form `#RRGGBB`.
#<cldoc:Color::Red>
Specifies a bright red color.
This has the value `#FF0000`.
Here, the first line is placed in brief documentation with the rest in the doc section. When viewed using index.html
, the brief section is ignored, so you get:
enum class Color
| These colors are assocated with CSS-style `RGB` values of the form `#RRGGBB`.
Red : 0 : This has the value `#FF0000`.
Green : 1 : This has the value `#00FF00`.
Blue : 2 : This has the value `#0000FF`.
This makes it difficult to document specifics for an enumeration/enumeration value (referencing external specifications, detailing usage, giving examples, etc.).
cldoc -Wall -Werror-implicit-function-declaration -std=c++11 -Iinclude -- --output doc include/gloglotto include/gloglotto/shader include/gloglotto/thin.tpp include/gloglotto/shader_manager.tpp include/gloglotto/exception include/gloglotto/maths include/gloglotto/maths/matrix.tpp include/gloglotto/maths/matrix include/gloglotto/maths/vector include/gloglotto/maths/vector.tpp include/gloglotto/shader.tpp include/gloglotto/shader_manager include/gloglotto/math include/gloglotto/utility include/gloglotto/thin include/gl source/shader.cpp source/shader_manager.cpp source/thin.cpp source/exception.cpp
Processing `gloglotto'
Traceback (most recent call last):
File "/usr/bin/cldoc", line 5, in <module>
cldoc.run()
File "/usr/lib/python2.7/site-packages/cldoc/__init__.py", line 152, in run
generate(opts, cxxflags)
File "/usr/lib/python2.7/site-packages/cldoc/__init__.py", line 23, in generate
t.process()
File "/usr/lib/python2.7/site-packages/cldoc/tree.py", line 208, in process
tu = index.parse(f, self.flags + includepaths.flags)
File "/usr/lib/python2.7/site-packages/cldoc/clang/cindex.py", line 1885, in parse
self)
File "/usr/lib/python2.7/site-packages/cldoc/clang/cindex.py", line 2026, in from_source
return cls(ptr, index=index)
File "/usr/lib/python2.7/site-packages/cldoc/clang/cindex.py", line 2058, in __init__
ClangObject.__init__(self, ptr)
File "/usr/lib/python2.7/site-packages/cldoc/clang/cindex.py", line 1655, in __init__
assert isinstance(obj, c_object_p) and obj
AssertionError
Exception ctypes.ArgumentError: "argument 1: <type 'exceptions.AttributeError'>: 'TranslationUnit' object has no attribute '_as_parameter_'" in <bound method TranslationUnit.__del__ of <cldoc.clang.cindex.TranslationUnit object at 0xe72310>> ignored
The distribution is Arch Linux, libclang is version 3.2, Python is 2.7.3.
The code can be found here, I tried with a simpler example and it works, so it's totally my code breaking it.
I've installed cldic using pip on mac os x 10.9.1. It doesn't seem to matter what command line options I pass cldoc, it only prints the help.
Please use: cldoc [command] [OPTIONS] [FILES...]
Available commands:
inspect
serve
generate
gir
What is the appropriate way to invoke cldoc on mac?
cldoc failed to parse the following simple code:
const char FOO[] = "foo";
Versions:
Backtrace:
$ cldoc generate -- --output html aaa.hpp
Processing `aaa.hpp'
Traceback (most recent call last):
File "/usr/local/bin/cldoc", line 9, in <module>
load_entry_point('cldoc==1.5', 'console_scripts', 'cldoc')()
File "/usr/local/lib/python2.7/dist-packages/cldoc/__init__.py", line 57, in run
run_generate(rest)
File "/usr/local/lib/python2.7/dist-packages/cldoc/__init__.py", line 27, in run_generate
cmdgenerate.run(args)
File "/usr/local/lib/python2.7/dist-packages/cldoc/cmdgenerate.py", line 133, in run
t.process()
File "/usr/local/lib/python2.7/dist-packages/cldoc/tree.py", line 142, in process
self.visit(tu.cursor.get_children())
File "/usr/local/lib/python2.7/dist-packages/cldoc/tree.py", line 408, in visit
node = cls(item, None)
File "/usr/local/lib/python2.7/dist-packages/cldoc/nodes/variable.py", line 23, in __init__
self.type = Type(cursor.type)
File "/usr/local/lib/python2.7/dist-packages/cldoc/nodes/ctype.py", line 57, in __init__
self.extract(tp)
File "/usr/local/lib/python2.7/dist-packages/cldoc/nodes/ctype.py", line 116, in extract
if tp.kind in Type.kindmap:
File "/usr/local/lib/python2.7/dist-packages/cldoc/clang/cindex.py", line 1469, in kind
return TypeKind.from_id(self._kind_id)
File "/usr/local/lib/python2.7/dist-packages/cldoc/clang/cindex.py", line 1409, in from_id
raise ValueError,'Unknown type kind %d' % id
ValueError: Unknown type kind 114
With not having a test suite to compare input test cases with expected output, it is not possible to verify that (a) fixing bugs/adding new features does not break existing functionality, and (b) fixed bugs are not reintroduced.
Hello there!
Thanks for this awesome utility! I was tempted to use it a few months ago at my last gig, but unfortunately never got the chance until now. I'm excited to try it out and get some quality docs up for my personal C/C++ endeavors :)
Unfortunately, I'm running into a bit of a snag whenever I try to generate documentation for my project. After successfully running python setup.py generate
and python setup.py install
with coffee
, sass
, and inliner
all in my $PATH
, I encounter the following stack trace whenever attempting to use the inspect
, generate
, and gir
commands:
$ cldoc generate -- src
Traceback (most recent call last):
File "/home/kelly/.pythonbrew/pythons/Python-2.7/bin/cldoc", line 5, in <module>
pkg_resources.run_script('cldoc==1.4', 'cldoc')
File "/home/kelly/.pythonbrew/pythons/Python-2.7/lib/python2.7/site-packages/distribute-0.6.49-py2.7.egg/pkg_resources.py", line 507, in run_script
self.require(requires)[0].run_script(script_name, ns)
File "/home/kelly/.pythonbrew/pythons/Python-2.7/lib/python2.7/site-packages/distribute-0.6.49-py2.7.egg/pkg_resources.py", line 1272, in run_script
execfile(script_filename, namespace, namespace)
File "/home/kelly/.pythonbrew/pythons/Python-2.7/lib/python2.7/site-packages/cldoc-1.4-py2.7.egg/EGG-INFO/scripts/cldoc", line 5, in <module>
cldoc.run()
File "/home/kelly/.pythonbrew/pythons/Python-2.7/lib/python2.7/site-packages/cldoc-1.4-py2.7.egg/cldoc/__init__.py", line 57, in run
run_generate(rest)
File "/home/kelly/.pythonbrew/pythons/Python-2.7/lib/python2.7/site-packages/cldoc-1.4-py2.7.egg/cldoc/__init__.py", line 27, in run_generate
cmdgenerate.run(args)
File "/home/kelly/.pythonbrew/pythons/Python-2.7/lib/python2.7/site-packages/cldoc-1.4-py2.7.egg/cldoc/cmdgenerate.py", line 111, in run
from . import tree
File "/home/kelly/.pythonbrew/pythons/Python-2.7/lib/python2.7/site-packages/cldoc-1.4-py2.7.egg/cldoc/tree.py", line 21, in <module>
import nodes
File "/home/kelly/.pythonbrew/pythons/Python-2.7/lib/python2.7/site-packages/cldoc-1.4-py2.7.egg/cldoc/nodes/__init__.py", line 30, in <module>
from .templatetype import *
ImportError: No module named templatetype
I compiled and installed cldoc on a 64-bit ArchLinux machine, and the project I'm attempting to generate documentation for is written entirely in C.
I'm also using PythonBrew -- not sure if that's of any importance.
Any pointers? Thanks in advance!
Sorry: this bug belongs to other github.
My apologize
To the admin: Pls delete this bug
Thanks
I am trying to run cldoc and am getting the following error:
Traceback (most recent call last):
File "C:\Python27\Scripts\cldoc.py", line 5, in
pkg_resources.run_script('cldoc==1.4', 'cldoc')
File "C:\Python27\lib\site-packages\pkg_resources.py", line 489, in run_script
self.require(requires)[0].run_script(script_name, ns)
File "C:\Python27\lib\site-packages\pkg_resources.py", line 1207, in run_script
execfile(script_filename, namespace, namespace)
File "c:\python27\lib\site-packages\cldoc-1.4-py2.7.egg\EGG-INFO\scripts\cldoc", line 3, in
import cldoc
File "C:\Python27\Scripts\cldoc.py", line 5, in
pkg_resources.run_script('cldoc==1.4', 'cldoc')
File "C:\Python27\lib\site-packages\pkg_resources.py", line 489, in run_script
self.require(requires)[0].run_script(script_name, ns)
File "C:\Python27\lib\site-packages\pkg_resources.py", line 1207, in run_script
execfile(script_filename, namespace, namespace)
File "c:\python27\lib\site-packages\cldoc-1.4-py2.7.egg\EGG-INFO\scripts\cldoc", line 5, in
cldoc.run()
AttributeError: 'module' object has no attribute 'run'
I have Python 2.7.4.
Given:
namespace foo { void bar(); }
The function has the entry:
<function id="bar" name="bar">...</function>
This is wrong, as the id is not fully qualified. It should be:
<function id="foo::bar" name="bar">...</function>
Removing the qid
property from cldoc/nodes/function.py
fixes this issue, but I don't know why this override was created in the first place (note: method.py
overrides qid
to use the Node
version and not the incorrect Function
version).
Given the markdown file:
#<cldoc:test>
A test.
@a The first parameter.
The parameter is correctly documented, but given:
#<cldoc:test>
A test.
@a The first parameter.
The parameter documentation is ignored.
Both of these should associate the parameter(s) with the specified documentation.
Currently (using master branch of git), such comment would lead to an empty brief description for class Chombier.
/*
* Chombier is something that does Blah() things.
*
* Chombier is clearly the awesomeness to do Blah() thing. It does
* just Blah(), and it do it well.
*/
class Chombier {
public :
void Blah();
};
Only this syntax would lead to a non empty brief description :
/* Chombier is something that does Blah() things.
*
* Chombier is clearly the awesomeness to do Blah() thing. It does
* just Blah(), and it do it well.
*/
class Chombier {
public :
void Blah();
};
Its a personnal taste but I like the first one, as I found it clearer.
Furthermore should not the tool be more pedantic and consider an empty (or only whitespace content) description as warning / error, and be reported in the report ? Like considered undocumented in the report, and in the program output a warning for a documented object without or with an empty brief description ?
Maybe it should be a separate issue ...
If you have two symbols (foo
and bar
) that you want to place in a group, you cannot do that in the markdown documentation. For example:
cldoc:begin-category(my_group)
#<cldoc:foo>
#<cldoc:bar>
cldoc:end-category()
results in the Failed to merge file 'test.md': no #<cldoc:id> specified
.
Given the following documentation (tested in a merged markdown file):
#<cldoc:foo>
Brief description.
@return Return description.
Detailed description.
The detailed description is ignored. Placing the @return
at the end causes the detailed description to be included.
It should not matter which order these are included in the documentation.
A common mistake when cldoc-ing a document is to leave the first comment line empty.
/*
* A does <Thing>
*/
class A{
public:
void Thing();
};
This will create a documention with an empty brief and a non-empty long description, as clearly the intention of the user here is to provide just a brief documentation.
I would like to use a more current version of clang that the one provided in my system. How can I select which one to use?
The instructions to simply use
pip install cldoc
to install cldoc are missing several points:
apt-get install python-pip
on Debian Linux).pyparsing
to be installed as well.sudo pip install ...
) otherwise it fails to write to /usr/local/lib/...
with a Permission denied
error.So the correct installation instructions are (for Debian-based systems):
sudo apt-get install python-pip
sudo pip install pyparsing
sudo pip install cldoc
Hi,
I've been using cldoc to write documentation for a program written in C. It is to be maintained by someone else, so writing clean and clear documentation is really important. I was drawn to cldoc instead of doxygen because of the quality of produced documentation, and ease of use.
However, I have some issues right now, which are stopping me from effectively using cldoc. Unfortunately, I am unable to show the code that is causing the issues, I appreciate this will make fixing much more difficult or perhaps impossible, but I'd much attempt to have the issues addressed than switch to doxygen.
Explicate categorisation doesn't seem to work all the time. Being a C program, this feature is pretty important to me. cldoc will usually adhere to the explicate categorisation, but some of my groups simply do not appear on the produced documentation. It is dependant on what is inside the category though. One such cause I seem to have tracked down - a category cannot end on a preprocessor macro. There are other causes that make a category disappear, but I am yet to identify them.
Pointers to incomplete types generate poor symbol names. Functions and structs that use pointers to incomplete types end up having their symbol name as the full path of the file they are defined in, and the symbol name. Example:
//file header_1.h
struct _new_type;
/*
documentation..
*/
void function(struct _new_type *arg1);
//file header_2.h
typedef struct _new_type
{
//etc.
} new_type;
In the resulting documentation for header_1.h
, we have
void
function (/Full/path/to/header_2.h::new_type *arg)
documentation..
So, cldoc seems to be resolving the definition of the type, just not formatting it correctly.
Some symbols in a group are arbitrarily moved on to their own page in a "more information on a separate page.." link. I do not want this, and I can't seem to stop it from happening. I suppose when cldoc decides that some functions belong to a struct, and the resulting group is larger than a certain size, then this happens.
No static html. I like the resulting documentation, but it'd be much more useful if I didn't have to run a HTTP server to view it.
Overall, I'm really enjoying using cldoc. I hope I can find some resolution to these issues, as I'd very much like to continue using it!
Thanks,
When cldoc generates documentation for a project that contains warnings, it exits on encountering the first warning, generating no documentation.
Given:
std::list<std::string> foo();
The XML output expands the typedef in the return type:
<return>
<type name="std::list<std::basic_string<char>, std::allocator<std::basic_string<char> > >" qualifier=" const &" />
</return>
In other contexts, e.g.:
void foo(const std::string &)
the argument type preserves the typedef:
<type name="std::string" qualifier=" const &" />
Both contexts should use the typedef alias. That is, the return type should be:
<return>
<type name="std::list<std::string, std::allocator<std::string> >" qualifier=" const &" />
</return>
I installed cldoc
via pip
and I get the following error when running make doc
in the example
folder.
Generating documentation...
Processing `bicycle.cc'
Processing `mountainbike.cc'
Processing `racingbike.cc'
Processing `transport.hh'
Generated `html/xml'
Traceback (most recent call last):
File "/usr/local/bin/cldoc", line 5, in <module>
cldoc.run()
File "/Library/Python/2.7/site-packages/cldoc/__init__.py", line 152, in run
generate(opts, cxxflags)
File "/Library/Python/2.7/site-packages/cldoc/__init__.py", line 33, in generate
generators.Html(t).generate(opts.output)
File "/Library/Python/2.7/site-packages/cldoc/generators/html.py", line 37, in generate
shutil.copyfile(index, outfile)
File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/shutil.py", line 81, in copyfile
with open(src, 'rb') as fsrc:
IOError: [Errno 2] No such file or directory: '/Library/Python/2.7/site-packages/cldoc/data/index.html'
make: *** [doc] Error 1
Hello,
I'm currently giving a try to cldoc (tag 1.2), on Archlinux (llvm-clang 3.2). I can't get any documentation generated, even with a very simple file. Here's my "test.cpp":
#include <iostream>
/* Exit code helper
*
* Absolutely useless, only here to test cldoc.
*/
class A {
public:
A() {
_exitcode = 0;
}
virtual ~A() {}
// Default exit code
inline int exitcode() const {
return _exitcode;
}
private:
int _exitcode;
};
void hello_world() {
std::cout << "Hello, world!" << std::endl;
}
int main() {
A a;
hello_world();
return a.exitcode();
}
I invoke cldoc like this: cldoc -- --output doc test.cpp
. The generated site is empty (only the two divs, and nothing inside of them). The XML is not really better:
<?xml version='1.0' encoding='utf-8'?>
<index />
However, if I run make doc
in the cldoc example, all works fine… I tried to add the --report
option, it generates the report page, but without any data.
When documenting a function namespace ns { void test(int a); }
, using <a>
results in:
<ref ref="ns#test::a">test::a</ref>
where it should produce:
<ref ref="ns#test::a">a</ref>
since it is within the function's scope.
Given:
std::list<std::string> foo();
The XML output for the return type is:
<return>
<type name="std::list<std::basic_string<char>, std::allocator<std::basic_string<char> > >" qualifier=" const &" />
</return>
This is including the allocator argument which is the default version from the template declaration. Thus, the allocator should not be present in the output, which should be:
<return>
<type name="std::list<std::basic_string<char> >" qualifier=" const &" />
</return>
With issue #50 fixed, this should be:
<return>
<type name="std::list<std::string>" qualifier=" const &" />
</return>
On Debian and Ubuntu systems, libclang
is provided by the libclang1
package. This installs /usr/lib/libclang.so.1
on amd64 and i386 systems, not /usr/lib/libclang.so
(see e.g. http://packages.ubuntu.com/raring/amd64/libclang1/filelist).
This means that running cldoc I get the error:
Traceback (most recent call last):
File "/usr/local/bin/cldoc", line 5, in <module>
cldoc.run()
File "/usr/local/lib/python2.7/dist-packages/cldoc/__init__.py", line 152, in run
generate(opts, cxxflags)
File "/usr/local/lib/python2.7/dist-packages/cldoc/__init__.py", line 23, in generate
t.process()
File "/usr/local/lib/python2.7/dist-packages/cldoc/tree.py", line 200, in process
index = cindex.Index.create()
File "/usr/local/lib/python2.7/dist-packages/cldoc/clang/cindex.py", line 1862, in create
return Index(conf.lib.clang_createIndex(excludeDecls, 0))
File "/usr/local/lib/python2.7/dist-packages/cldoc/clang/cindex.py", line 153, in __get__
value = self.wrapped(instance)
File "/usr/local/lib/python2.7/dist-packages/cldoc/clang/cindex.py", line 3096, in lib
lib = self.get_cindex_library()
File "/usr/local/lib/python2.7/dist-packages/cldoc/clang/cindex.py", line 3127, in get_cindex_library
raise LibclangError(msg)
cldoc.clang.cindex.LibclangError: libclang.so: cannot open shared object file: No such file or directory. To provide a path to libclang use Config.set_library_path() or Config.set_library_file().
Hello there, Rubyist (and Mac developer) here who is super interested in cldoc for Cocoapods. I seem to be at a confusing position though.
I tried installing cldoc via pip, but it turns out it's not installed on an OSX box, so I installed Python & Pip, which by default installed 2.7. Which cannot install pyparsing 2.x.
As with the website linked above I had to manually install an older build of pyparsing pip install pyparsing==1.5.7
and then could install cldoc. So I guess if there's a part of the pip install script where you can set a dependency you need to give a version.
git clone https://github.com/idupree/Lasercake.git
cd Lasercake
cldoc -w -std=c++0x -I$PWD/boostbcp -- --output html config.hpp debug_print_deterministically.hpp input_representation.hpp object_and_tile_iteration.hpp specific_object_types.hpp specific_worlds.hpp tile_iteration.hpp tile_physics.hpp tiles.hpp units.hpp utils.hpp world.hpp world_constants.hpp worldgen.hpp
Processing `config.hpp'
Processing `debug_print_deterministically.hpp'
Processing `input_representation.hpp'
Processing `object_and_tile_iteration.hpp'
Unhandled cursor: CursorKind.DECL_REF_EXPR
Unhandled cursor: CursorKind.DECL_REF_EXPR
Unhandled cursor: CursorKind.CLASS_TEMPLATE_PARTIAL_SPECIALIZATION
Unhandled cursor: CursorKind.TEMPLATE_NON_TYPE_PARAMETER
Unhandled cursor: CursorKind.DECL_REF_EXPR
Unhandled cursor: CursorKind.DECL_REF_EXPR
Unhandled cursor: CursorKind.DECL_REF_EXPR
Unhandled cursor: CursorKind.DECL_REF_EXPR
Unhandled cursor: CursorKind.DECL_REF_EXPR
Unhandled cursor: CursorKind.DECL_REF_EXPR
Unhandled cursor: CursorKind.DECL_REF_EXPR
Traceback (most recent call last):
File "/Users/me/HOME/.local/bin/cldoc", line 5, in <module>
cldoc.run()
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/__init__.py", line 152, in run
generate(opts, cxxflags)
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/__init__.py", line 23, in generate
t.process()
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/tree.py", line 240, in process
self.visit(tu.cursor.get_children())
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/tree.py", line 521, in visit
self.visit(item.get_children(), node)
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/tree.py", line 521, in visit
self.visit(item.get_children(), node)
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/tree.py", line 515, in visit
self.register_anon_typedef(node, parent)
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/tree.py", line 447, in register_anon_typedef
self.all_nodes.remove(parent)
ValueError: list.remove(x): x not in list
(-w because of issue #3. -I$PWD/boostbcp is probably unnecessary if you have boost>=1.50 headers installed.)
When I replaced that line with
try: self.all_nodes.remove(parent)
except ValueError: sys.stderr.write('BIG ERROR\n')
it got through all the files and then threw other exceptions like
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/nodes/method.py", line 37, in override
bases = list(self.parent.bases)
AttributeError: 'Namespace' object has no attribute 'bases'
or
File "/Users/me/HOME/.local/lib/python2.7/site-packages/cldoc/nodes/ctype.py", line 61, in is_array
return self.tp.kind == cindex.TypeKind.CONSTANTARRAY
AttributeError: 'TemplateType' object has no attribute 'tp'
I'd like to use your code to document mine, but first it has to survive processing the current state of my sources! Tell me whether you can reproduce the errors with my instructions. I have no idea where to start in creating a minimal test-case: I don't know your code yet, and I failed to get any errors if I processed a single header file alone (I didn't try all of them though). For reference, my local cldoc
correctly processes the example project in your repo ("correctly" meaning the same output as http://jessevdk.github.com/cldoc/example/ by visual inspection).
System: Arch Linux
clang: 3.2
python2: 2.7.3
pyparsing: 1.5.7
cldoc: 1.2, installed via pip (via pip2, to be precise, so that it uses python 2; I'm happy to test for python 3 compatibility once it works at all for me.)
Add an example that shows how to configure cldoc with cmake to use the same flags as in a build using clang and to get all the headers/cpp files from CMake.
I see that cldoc has a feature to merge Markdown-formatted files into the documentation. What exactly does it mean to merge a Markdown-formatted file into the documentation?
For example, say my Markdown file was:
## Section
Hello, World!
#### Sub Section
One more time!
Where would this text be placed in the documentation produced by cldoc?
Given a struct/class foo
that has the following documentation in markdown:
You can create a `foo` object using:
std::shared_ptr<foo> f = create_foo();
This results in the xml:
<doc>You can create a `foo` object using:
std::shared_ptr<ref ref="foo#foo">foo</ref> f = create_foo();
</doc>
Therefore, the template brackets are lost -- the type for f
should be std::shared_ptr<<ref ref="foo#foo">foo</ref>>
, or references should not be expanded in code blocks (including backtick-style inline code):
<doc>You can create a `foo` object using:
std::shared_ptr<foo> f = create_foo();
</doc>
Hi
I have cloned cldoc to local.
But after I setup cldoc by python setup.py install
, I failed to use it to generate docs with the following error:
Traceback (most recent call last):
File "/usr/local/bin/cldoc", line 5, in <module>
pkg_resources.run_script('cldoc==1.4', 'cldoc')
File "/usr/local/lib/python2.7/dist-packages/pkg_resources.py", line 505, in run_script
self.require(requires)[0].run_script(script_name, ns)
File "/usr/local/lib/python2.7/dist-packages/pkg_resources.py", line 1245, in run_script
execfile(script_filename, namespace, namespace)
File "/usr/local/lib/python2.7/dist-packages/cldoc-1.4-py2.7.egg/EGG-INFO/scripts/cldoc", line 5, in <module>
cldoc.run()
File "/usr/local/lib/python2.7/dist-packages/cldoc-1.4-py2.7.egg/cldoc/__init__.py", line 57, in run
run_generate(rest)
File "/usr/local/lib/python2.7/dist-packages/cldoc-1.4-py2.7.egg/cldoc/__init__.py", line 27, in run_generate
cmdgenerate.run(args)
File "/usr/local/lib/python2.7/dist-packages/cldoc-1.4-py2.7.egg/cldoc/cmdgenerate.py", line 140, in run
run_generate(t, opts)
File "/usr/local/lib/python2.7/dist-packages/cldoc-1.4-py2.7.egg/cldoc/cmdgenerate.py", line 34, in run_generate
generators.Html(t).generate(baseout, opts.static, opts.custom_js, opts.custom_css)
File "/usr/local/lib/python2.7/dist-packages/cldoc-1.4-py2.7.egg/cldoc/generators/html.py", line 40, in generate
with open(index) as f:
IOError: [Errno 2] No such file or directory: '/usr/local/lib/python2.7/dist-packages/cldoc-1.4-py2.7.egg/cldoc/data/index.html'
make: *** [doc] Error 1
I noticed that the error was caused by the missing directory of 'cldoc/data'.
However, if I install cldoc by `pip``, it works fine.
I found 'cldoc/data' in the tar ball from pip, but not from the github repo.
Could you help me solve this problem?
Given:
void test(int a);
void test(float val);
it is not possible to specify which overload is being documented (such that each function gets the correct documentation, e.g. in the XML output) -- the descriptions get merged into the last matching overload.
Processing `bicycle.cc'
warning: generate: 'linker' input unused [-Wunused-command-line-argument]
Traceback (most recent call last):
File "/usr/bin/cldoc", line 5, in <module>
cldoc.run()
File "/usr/lib/python2.7/site-packages/cldoc/__init__.py", line 169, in run
generate(opts, cxxflags)
File "/usr/lib/python2.7/site-packages/cldoc/__init__.py", line 37, in generate
t.process()
File "/usr/lib/python2.7/site-packages/cldoc/tree.py", line 243, in process
db = comment.CommentsDatabase(e, tu)
File "/usr/lib/python2.7/site-packages/cldoc/comment.py", line 250, in __init__
self.extract(filename, tu)
File "/usr/lib/python2.7/site-packages/cldoc/comment.py", line 326, in extract
it = tu.get_tokens(extent=tu.get_extent(filename, (0, os.stat(filename).st_size)))
File "/usr/lib/python2.7/site-packages/cldoc/clang/cindex.py", line 2150, in get_extent
assert isinstance(end_location, SourceLocation)
AssertionError
I'm running this under arch linux, installed cldoc with pip2.
Started cldoc through the makefile doc target. cldoc is started with python2.7
If I'm often temporarily adding debug printf's in a file, I might have:
//#include <cstdio>
namespace foo {
}
However the first line gets parsed as markdown and becomes a gigantic heading documenting the namespace. There should be (or example added mentioning) syntax to comment code out without turning it into documentation.
This is related to #41 and hopefully the syntax for ignoring individual lines would be very simple, like ///.
First of all thanks for adding initial support for templates, as requested I've added the following patch to show a case where documentation is not generated for templated member functions.
Thanks for the great work so far.
diff --git a/example/transport/mountainbike.hh b/example/transport/mountainbike.hh
index 051bc89..0bf543f 100644
--- a/example/transport/mountainbike.hh
+++ b/example/transport/mountainbike.hh
@@ -28,6 +28,25 @@ namespace transport
* false otherwise.
*/
bool SetSuspension(double stiffness);
+
+ /* Change the break type.
+ * @breakType the type of the break.
+ *
+ * ChangesBreaks changes the type of break fitted to the bike.
+ * The method will return false if the break type could not be
+ * fitted.
+ *
+ * @return true if the break was adjusted successfully.
+ * false otherise
+ */
+ template <typename BreakType> bool ChangeBreak(BreakType breakType)
+ {
+ if(breakType)
+ {
+ return true;
+ }
+ return false;
+ }
};
}
I installed cldoc
via pip
for Python 2.7, and ran cldoc
on this library using the following command:
cldoc generate -std=c++11 -Wall -Wextra -pedantic -Wno-return-type-c-linkage -I include -I /opt/local/include -I /usr/include -- --output doc include/ccbase/*.hpp include/ccbase/*/*.hpp
The program failed after attempting to process unit_test.hpp
, and printed out the following stack trace:
Processing `unit_test.hpp'
/Users/aditya/projects/c++/ccbase/include/ccbase/unit_test/unit_test.hpp:202:1: warning: unused function 'parse_flags' [-Wunused-function]
Traceback (most recent call last):
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/bin/cldoc", line 9, in <module>
load_entry_point('cldoc==1.5', 'console_scripts', 'cldoc')()
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/__init__.py", line 57, in run
run_generate(rest)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/__init__.py", line 27, in run_generate
cmdgenerate.run(args)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/cmdgenerate.py", line 133, in run
t.process()
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/tree.py", line 142, in process
self.visit(tu.cursor.get_children())
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/tree.py", line 423, in visit
self.visit(item.get_children(), node)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/tree.py", line 423, in visit
self.visit(item.get_children(), node)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/tree.py", line 408, in visit
node = cls(item, None)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/nodes/variable.py", line 23, in __init__
self.type = Type(cursor.type)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/nodes/ctype.py", line 57, in __init__
self.extract(tp)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/nodes/ctype.py", line 116, in extract
if tp.kind in Type.kindmap:
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/clang/cindex.py", line 1469, in kind
return TypeKind.from_id(self._kind_id)
File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/cldoc/clang/cindex.py", line 1409, in from_id
raise ValueError,'Unknown type kind %d' % id
ValueError: Unknown type kind 114
The complete output of the command is available here. Let me me know if you need any more information, or would like me to try something else. Thanks!
Hi, I just discovered cldoc today and now I'm trying to make it work with my project so I can dump doxygen.
The first problem I found is that including some standard header files causes problems. For example, adding this line to bicycle.hh:
#include <cassert>
Causes:
Processing `bicycle.hh'
/usr/include/sys/resource.h:193:2: error: unknown type name 'uint8_t'
/usr/include/sys/resource.h:194:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:195:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:196:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:197:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:198:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:199:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:200:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:201:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:202:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:203:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:207:2: error: unknown type name 'uint8_t'
/usr/include/sys/resource.h:208:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:209:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:210:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:211:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:212:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:213:2: error: unknown type name 'uint64_t'
/usr/include/sys/resource.h:214:2: error: unknown type name 'uint64_t'
fatal error: too many errors emitted, stopping now [-ferror-limit=]
Could not generate documentation due to parser errors
I know nothing about libclang or cldoc yet, so I don't know how to start debugging this problem... but I assume it has to do with discrepancies in clang's environment (when called by cldoc, as opposed to Xcode)? I tried passing all the CXXFLAGS that Xcode was passing to clang but nothing solved the problem...
I hope you're on OSX too? Otherwise could you please teach me how to debug this? Thanks
I've got a class.h and a class-inl.h with its inline functions. #pragma once seems to have problems if class.h includes class-inl.h at the end. To successfully parse class-inl.h when cldoc runs clang on it, it must include class.h creating a circular dependency. When cldoc processes class.h, #pragma once is ignored because it's the main file. Then class-inl.h includes it again and clang fails to parse.
This has been discussed before in issue #4.
A workaround is to not have cldoc parse class-inl.h files and place no documentation there. Then the #include class.h can be removed from them.
When cldoc generates documentation for header files with the .hpp ending, they are treated as if they were .c/.cpp/.cxx files.
This is a problem, because Clang generates a warning when it encounters a #pragma once directive in a main file, and due to issue #3, this causes cldoc to exit immediately.
This is only a pet peeve, but C++ doesn't have methods. Rather the terms free function or ( non-member function ) and member function are used.
Using cldoc 1.6, having a markdown file with:
# License
Description of the license for the file.
#<cldoc:test>
Test documentation.
Causes a "Failed to merge file... no #cldoc:id specified" error.
Doing the reverse:
#<cldoc:test>
Test documentation.
# License
Description of the license for the file.
Causes test
to have a <doc>#License Description of the license for the file.</doc>
node associated with it.
Doing:
#<cldoc:test>
Test documentation.
@return Some value.
# License
Description of the license for the file.
does not cause the License section to be added to the documentation.
In all these cases, the additional header contents should be ignored as in markdown this should create a new section.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.