3

This question was flagged as unclear what I'm asking. For clarity, I am asking for a workaround to get this document generator working properly against my codebase. (perhaps splitting the job into batches? Is that possible with cldocs? Perhaps issuing different command line options? Perhaps my invocation is wrong or misguided?)

I have filed a bug against the project that you can find here with some additional information about my environment (including a full command line located here: http://pastebin.com/JxWf9hRB).

https://github.com/jessevdk/cldoc/issues/73

Original Question:

I'm investigating using cldocs for automated documentation. However, it's crashing on my codebase, with the following error:

Traceback (most recent call last):
  File "/usr/local/bin/cldoc", line 9, in <module>
    load_entry_point('cldoc==1.6', 'console_scripts', 'cldoc')()
  File "/usr/local/lib/python2.7/site-packages/cldoc/__init__.py", line 57, in run
    run_generate(rest)
  File "/usr/local/lib/python2.7/site-packages/cldoc/__init__.py", line 27, in run_generate
    cmdgenerate.run(args)
  File "/usr/local/lib/python2.7/site-packages/cldoc/cmdgenerate.py", line 151, in run
    run_generate(t, opts)
  File "/usr/local/lib/python2.7/site-packages/cldoc/cmdgenerate.py", line 33, in run_generate
    generator.generate(xmlout)
  File "/usr/local/lib/python2.7/site-packages/cldoc/generators/xml.py", line 55, in generate
    Generator.generate(self, outdir)
  File "/usr/local/lib/python2.7/site-packages/cldoc/generators/generator.py", line 22, in generate
    self.generate_node(node)
  File "/usr/local/lib/python2.7/site-packages/cldoc/generators/xml.py", line 543, in generate_node
    self.generate_page(node)
  File "/usr/local/lib/python2.7/site-packages/cldoc/generators/xml.py", line 510, in generate_page
    elem = self.node_to_xml(node)
  File "/usr/local/lib/python2.7/site-packages/cldoc/generators/xml.py", line 496, in node_to_xml
    chelem = self.node_to_xml(child)
  File "/usr/local/lib/python2.7/site-packages/cldoc/generators/xml.py", line 485, in node_to_xml
    self.call_type_specific(node, elem, 'to_xml')
  File "/usr/local/lib/python2.7/site-packages/cldoc/generators/xml.py", line 465, in call_type_specific
    getattr(self, nm)(node, elem)
  File "/usr/local/lib/python2.7/site-packages/cldoc/generators/xml.py", line 273, in method_to_xml
    if len(node.override) > 0:
  File "/usr/local/lib/python2.7/site-packages/cldoc/nodes/method.py", line 43, in override
    bases = list(self.parent.bases)
AttributeError: 'Namespace' object has no attribute 'bases'

EDIT:

After a long while, I have been able to pare it down to a minimal example.

template<typename T>
struct Foo {
  int baz(T const& t) const { }
};

template<typename T, int N>
class Bar { };

template<typename T, int N>
struct Foo<Bar<T, N>> {
  int baz(Bar<T, N> const& a) const;
};

template<typename T, int N>
int Foo<Bar<T, N>>::baz(Bar<T, N> const& a) const { }

Whereas this works:

template<typename T>
struct Foo {
  int baz(T const& t) const { }
};

template<typename T, int N>
class Bar { };

template<typename T, int N>
struct Foo<Bar<T, N>> {
  int baz(Bar<T, N> const& a) const { }
};
OmnipotentEntity
  • 16,531
  • 6
  • 62
  • 96
  • can you split the command into several other shorter ones? I'm thinking the command line buffer might overflow -hence your problems – Pandrei Dec 02 '14 at 15:43
  • @Pandrei, I was wrong about the issue being length. The issue seems to be certain structures which are not handled properly by the parser. I've included a minimal example. – OmnipotentEntity Dec 03 '14 at 22:10
  • Out of the blue, some desperate ideas that might be worth trying, just in case: 1) Have you tried separating the brackets, i.e using "> >" instead of ">>" (unlikely to solve the issue considering the working example has some ">>" as well). 2) Have you tried to change the name of template parameter of Foo from "T" to "U"? (there *might* be a name-clash bug of the parser between the two "T" that you use locally for different things). – Boris Dalstein Dec 04 '14 at 08:43
  • Oh, nevermind, I just saw that your bug entry has an answer stating what the bug of cldoc is (different than what I suggested). – Boris Dalstein Dec 04 '14 at 08:47

1 Answers1

1

First of all cldoc relies on clang in parsing the sources, it requires proper C/C++ flags (e.g. -std=c++11) to operate properly.

Then, even with proper flags it explodes on certain constructions which look valid. Particularly it attempts to process out of template class method definitions with a seemingly wrong context. Particularly the problem with the Foo<Bar<T, N>>::baz() definition is that during processing its self.parent is equal to Root or Namespace objects (which obviously don't have "bases" attribute and shouldn't have), not Class or alike object, for which bases are used to track down overrides list for a particular method.

I've prepared a workaround for the problem which simply "relaxes" manipulations with self.parent attributes at the point of explosion and have posted it as a comment to the issue. But certainly it's not the solution. Perhaps a proper solution should first decide if such out-of-class method definitions have to be processed this way at all, probably a correct way is to handle overrides list at methods declarations only.

Here's the patch:

diff --git a/cldoc/nodes/method.py b/cldoc/nodes/method.py
index f910241..3e1208f 100644
--- a/cldoc/nodes/method.py
+++ b/cldoc/nodes/method.py
@@ -40,7 +40,7 @@ class Method(Function):
             return self._override

         # Lookup in bases, recursively
-        bases = list(self.parent.bases)
+        bases = list(getattr(self.parent, "bases", []))
         mname = self.name

         self._override = []
user3159253
  • 16,836
  • 3
  • 30
  • 56