jessevdk / cldoc Goto Github PK

clang based documentation generator for C and C++

License: GNU General Public License v2.0

Python 47.61% JavaScript 8.02% CMake 0.25% C++ 0.98% CoffeeScript 9.43% CSS 2.36% Shell 0.11% Makefile 0.24% HTML 31.01%

cldoc's Introduction

cldoc is a clang based documentation generator for C and C++. cldoc tries to solve the issue of writing C/C++ software documentation with a modern, non-intrusive and robust approach.

Features

Uses clang to robustly parse even the most complex C++ projects without additional effort from the user.
Requires zero configuration.
Uses markdown for documentation formatting.
Generates an xml description of the API which can be reused for other purposes.
Uses a simple format for documenting your code.
Supports cross-referencing in documentation.
Generates a single file, javascript based web application to render the documentation.
Integrates seamlessly with your existing website.
Lightning fast client-side searching using a pregenerated search index.
Generates a formatted documentation coverage report and integrates it in the website.

For more information, please visit http://jessevdk.github.com/cldoc.

Requirements

cldoc requires clang 3.9 or later to be installed on the system.

Get started now!

To get started using cldoc, please have a look at Getting started to install cldoc. Then explore how to document your code so that cldoc can extract it. Finally go and read Generating site to find out how to use the cldoc command in your project to generate the documentation.

Example

For an easy introduction into using cldoc, please have a look at the example project and corresponding generated documentation.

cldoc's People

Contributors

Stargazers

Watchers

cldoc's Issues

An operator in a namespace does not preserve the namespace scope.

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).

AttributeError: 'module' object has no attribute 'run'

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.

xcode integration?

cldoc treats .hpp files as main files

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.

Only printing help...

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?

Return types of templates are not generated

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.

Functions in a namespace have the wrong id

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).

Problem parsing standard header files on OSX 10.9 / Xcode 5

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

Use CMake JSON compilation database

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.

Template brackets get lost in markdown codeblocks for references

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>

Markdown processing does not allow/support non-documentation sections

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.

Cannot define categories in markdown documentation

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.

libclang.so cannot open shared object

Sorry: this bug belongs to other github.
My apologize
To the admin: Pls delete this bug
Thanks

cldoc exits with an error when encountering a warning

When cldoc generates documentation for a project that contains warnings, it exits on encountering the first warning, generating no documentation.

Typedefs not used for standard types in some contexts

Given:

std::list<std::string> foo();

The XML output expands the typedef in the return type:

<return>
  <type name="std::list&lt;std::basic_string&lt;char&gt;, std::allocator&lt;std::basic_string&lt;char&gt; &gt; &gt;" qualifier=" const &amp;" />
</return>

In other contexts, e.g.:

void foo(const std::string &)

the argument type preserves the typedef:

  <type name="std::string" qualifier=" const &amp;" />

Both contexts should use the typedef alias. That is, the return type should be:

<return>
  <type name="std::list&lt;std::string, std::allocator&lt;std::string&gt; &gt;" qualifier=" const &amp;" />
</return>

The getting started page should be more informative on installing cldoc

The instructions to simply use

pip install cldoc

to install cldoc are missing several points:

The pip program needs to be installed (apt-get install python-pip on Debian Linux).
The cldoc program needs pyparsing to be installed as well.
The pip program needs to be run as root (e.g. 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

C++11 deleted constructor and assignment

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.

C++ has no methods

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.

Missing directory cldoc/data

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?

Free template functions crash cldoc

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'

Assertion on TranslationUnit.

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.

Templated member functions not generated

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;
+       }
    };
 }

Allow first line of the comment to be blank, disallow an empty brief

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 ...

AttributeError: 'TemplateType' object has no attribute 'tp'

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

<cldoc:id> does not support overloaded function/method/... documentation

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.

index.html ignores brief documentation for enumerations

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.).

Syntax for commenting out code

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 ///.

generate and serve should detect empty brief description

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.

cldoc should treat documentation with an empty brief but a long description as a warning / error
cldoc should report these case once in the command line.

Can't generate any documentation

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.

C Document Error: Return type taking precedence over first parameter.

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);

Template classes not shown on index page

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.

<arg> references include function name

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.

ImportError: No module named templatetype

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!

Add a CMake example

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.

Circular dependency issue with #pragma once

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.

Default template parameter values are included in the type signature

Given:

std::list<std::string> foo();

The XML output for the return type is:

<return>
  <type name="std::list&lt;std::basic_string&lt;char&gt;, std::allocator&lt;std::basic_string&lt;char&gt; &gt; &gt;" qualifier=" const &amp;" />
</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&lt;std::basic_string&lt;char&gt; &gt;" qualifier=" const &amp;" />
</return>

With issue #50 fixed, this should be:

<return>
  <type name="std::list&lt;std::string&gt;" qualifier=" const &amp;" />
</return>

Choose a different lib

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?

ValueError: Unknown type kind 114 for const char[]

cldoc failed to parse the following simple code:

const char FOO[] = "foo";

Versions:

cldoc 1.5 (installed via pip)
clang 3.4

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

Failure with "Value Error: Unknown type kind 114"

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!

ValueError: list.remove(x): x not in list

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'

  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.)

Parameters don't get processed if there is a blank line after the brief documentation

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.

Question about merging markdown files

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?

Problems with documenting C

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,

Error locating libclang.so on Debian/Ubuntu systems

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().

Cannot place detailed descriptions after @return statements

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.

Not finding node.js on my system

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?

cldoc does not have a regression test suite

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.

cldoc example arch linux

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

make doc fails in example project with pip installed cldoc

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

pyparsing 2 requires python 3, and cldoc requires python 2

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.

jessevdk / cldoc Goto Github PK

cldoc's Introduction

Features

Requirements

Get started now!

Example

cldoc's People

Contributors

Stargazers

Watchers

Forkers

cldoc's Issues

Recommend Projects

Recommend Topics

Recommend Org