Problems with code examples in 1.21
Multi-language source code documentation tool
Brought to you by:
gregvalure
Menu
▾
▴
Hi there,
I started today to migrate one Javascript project of mine from doxygen to NaturalDocs. To be honest, though I still miss some features of doxygen I think NaturalDocs has the potential to beat doxygen and other automated documentation systems real soon (curious for the 2.0 release ;)
But to my actual problem. I have a javascript file and use C like block comments /**/. Whenever I try to use NaturalDoc code/graph chars on one comment line (>, | or :, tested all three) for single line or multiple line examples, the entire comment block vanishes from the page and menu without a warning from the generator script.
example:
/*
** About: examples
**
** some explanations
**
** > here should be the code example
**
** and some more explanation
**
*/
This example in that form doesnt work for me. Am I still doing something wrong?
Thx for your comments already in advance.
It works for me as shown above. The only way I was able to reproduce the error is if I omitted the space between the ** and the >. I'll investigate why that kills the comment, but for now, if you add the space between them it works fine.
Message from a different 'nobody', using version 1.34:
Is it possible to 'fix' the problem with the space between the ** and the > ? My comment blocks look like so
/*
*
*
*/
And sometimes I forget to put the space between the * and the :, and entire comment block is skipped, with no warnings, errors etc.
Also - the handling of hyphens within text is not what I might hope.
First, I had the number -1 in the text, and managed to get a line break between the minus and the 1.
Second, the behaviour to automatically create a 'definition' if you include a hyphen like so - in the paragraph means that hyphen usage is a bit restricted. Of course, this is okay in some ways, but when it's in the middle of a paragraph, I would guess it's fairly obvious it's not meant to be a definition. A suggestion - only trigger this 'definition' function if the text to the left of the hyphen is, what, 4 words or less?
Thanks for any help you can give,
John
I tweaked the definition behavior a bit for 1.35. It won't trigger if the line above it is plain text. It has to be blank or something like a heading. It's still not perfect but it should suck less. I've been looking for a reliable way to remove false positives here but I haven't found anything I'm completely happy with.
I'll look at the text line issue in another release.
Ack, you are right :(
That happens if you try to simplify examples afterwards. Well, here is the real non working example, and I have tracked the problem down to a reproducable point.
Like I have said I use block comments. And not only in the syntax meaning, but also in a graphical way. Something like:
***********************
*** ***
*** ***
***********************
Maybe thats part of the reason that leads to the problem. However, I found out that even in some other situations where I have forgotten the "closing" asterixes *** at the end of the line, the complete block will be ignored without any further notice of your perl script.
I hope the tested example here will look better in the forum than it does in this edit box *shiver*
/*** ***
*** ***
*** About: Quickstart Documentation ***
*** ***
*** The most simple way to use this object is to include the xLib d2jsp library in your ***
*** script like this ***
*** ***
*** > include("bla.js"); ***
*/
/*** ***
*** ***
*** About: Quickstart Documentation ***
*** ***
*** The most simple way to use this object is to include the xLib d2jsp library in your ***
*** script like this ***
*** ***
*** > include("bla.js");
*/
When you try this, only one "Quickstart Documentation" block will appear in the summery. I also tried different names to assure it's not the problem of double entries with same names.
Hope this more detailed description gets you closer to my problem :) Thx.
Yes, the problem is that you're not closing your box on the right side in your second example. Since the ending of each line isn't the same, it doesn't detect it as a vertical line, and thus doesn't clear it.
The reason the topic isn't appearing is because to start a topic, it has to be on the first comment line or the line above it has to be blank, not including boxes. Since the right side didn't clear, the line above it is "***" at that point in the parse, and the topic isn't detected.
Even if I changed this behavior, you would still have "***"s scattered throughout your output because the line wasn't cleared. It has to be completely continuous to be cleared.
Ahh, thanks for point this out! In the end it sounds quite obvious and simple :).
I think I was a little confused by the documentation about the "range" code examples, where you say the begin and end marker have to be the only statement on a line. I started testing with those but it didnt work, so I simplified the examples but didnt realize the border cause the trouble.
In the end I finally got the (start code) and (end code) thing to work, too. *slap self* Think of the border man, think of the border ;)
Thx again for your effords.