Problems with documenting C about cldoc HOT 8 OPEN

Hello, thanks for the report! I understand you can't just put up the code your working on but you're right that it would be a bit easier if you had some minimal example exposing the various issues. In any case, the initial focus has been a bit more on the C++ side, so some bugs for documenting C were to be expected. I think the first two issues will be not too difficult to solve, probably some minor bugs and I hope I can fix them quite soon. With regard to your third point, it's indeed the case that functions which receive as a first argument a pointer to a struct are moved automatically to a separate page for that struct. This happens as soon as there is at least one function for such a struct. Right now there isn't any setting or directive to change that. The fourth item is basically a feature that I want to implement, but it's not a very high priority (there are some more pressing, actual bugs, that should be fixed first).

Just to give you my point of view, I want cldoc to be a consistent, clear and easy to use documentation tool across different projects. In that mindset I don't plan to implement too many customizations on the generated output, at least not at first. The structure of the documentation should be the same everywhere, mostly. That said, of course the current behavior is not yet the ideal default, so I'm more than happy to get suggestions on improvements. I'll think a bit more about the third bullet point (I'm not completely satisfied myself with the "more information on separate page" items).

from cldoc.

Hi Jesse,

I've noticed an issue with creating C documentation as well. Looks like right now the functions are only getting categorized in one of the types associated with the function instead of all (return type, parameters). This would be incorrect behaviour right? If this is actually a bug and not just me misusing cldoc I may be able to pitch in and help fix it.

I need a good document generator for C code, like clang, and can't stand using doxygen.

from cldoc.

C functions are currently automatically moved to the page of the struct which is the first argument of the function (if there are more than N such functions). The idea is that often C API's are made like such:

struct _SomeType;
typedef struct _SomeType SomeType;

const char *some_type_get_name (SomeType *s);
void some_type_set_name (SomeType *s, const char *name);

/* etc */

i.e. the struct type represents a kind of object with API functions. Making this behavior the default is arguable, especially since not all C API works this way.

What you have in mind is something else, more like a "show me all functions that use this type as part of their signature". That's not what cldoc does right now. It's an interesting feature by itself, but something that I would expose as a kind of query I think.

from cldoc.

Ok, that makes sense and what I was expecting. What I am observing right now though is...

typedef int err_t;

typedef struct _bar_t bar_t;

err_t foo(bar_t *bar);

Where all functions are going to the return type err_t. Is that expected behaviour?

from cldoc.

No, that looks like a bug. Could you maybe open a separate issue for this?

from cldoc.

Will do.

from cldoc.

[SOLVED]

Hi, I am also trying to document some C code with cldoc. I'd like the functions to be categorized in the categories I specify, but it seems like the policy of grouping under the first argument struct (your comment on Dec 10, 2013) seems to override my specified category. What part of the source code should I go to to change this priority? Should I be looking in tree.py?

EDIT: Replacing line 332 in tree.py by parent = None did what I wanted.

from cldoc.

Hello, old issue but: Is there a workaround? Sorting the functions with a struct as first parameter to the struct does make no sense in my code...

from cldoc.