Improve generated comments

[dcharkes]

Sometimes, our generated comments are very long lines (above 80 chars).

/**
 * A cursor representing some element in the abstract syntax tree for
 * a translation unit.

->

/// A cursor representing some element in the abstract syntax tree for a translation unit.

Is there a way to get the original word wrapping from the comments? Or does clang_Cursor_getBriefCommentText remove the word wrapping altogether?

If it removes the word wrapping altogether, can we manually word wrap before we reach 80 chars?

Something like string.split(" ") and then join till below 76 characters (80 - '/// '.length) again.

Sidenote: maybe we should also support using clang_Cursor_getRawCommentText if people want the full C/C++ comments verbatim (only replacing the comment type with ///).

[dcharkes]

Another side note: We should also investigate why clang does not see comments on sqlite3.h. (Possibly because of the slightly strange comment syntax /*\n** the comment\n*/.)

[mannprerak2]

Is there a way to get the original word wrapping from the comments? Or does clang_Cursor_getBriefCommentText remove the word wrapping altogether?

The clang_Cursor_getBriefCommentText method returns the first paragraph only, while replacing any new lines with a 'space'. Which means we need to wrap the comment ourselves.

Another side note: We should also investigate why clang does not see comments on sqlite3.h. (Possibly because of the slightly strange comment syntax /*\n** the comment\n*/.)

The correct syntax for a doc comment is

/**
* Some comment string
* Another comment string
*/

The doc comment must start with a /** if clang_Cursor_getBriefCommentText is to return it.

maybe we should also support using clang_Cursor_getRawCommentText if people want the full C/C++ comments verbatim (only replacing the comment type with ///).

We can provide an option for them to get the Raw comment. And replace these - /**,*,*/ with this - ///

We currently have an option to turn off comments

extract-comments: true/false

We can replace it with

comments: 'brief'/'full'/'none'

And use brief as default

[mannprerak2]

Closed by PR dart-archive/ffigen#16