Problems with documenting C

[dancrn]

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.

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

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

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

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

[jessevdk]

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

[ghost]

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.

[jessevdk]

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.

[ghost]

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?

[jessevdk]

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

[ghost]

Will do.

[avikde]

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

[jounathaen]

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