www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - DDoc and single declarations

reply jicman <jicman_member pathlink.com> writes:
Greetings!

According to DDoc documentation, a declaration can have a comment to the right
of the declaration, ie.

int i = 0;   /// this is for i

and the comment will appear in the DDoc html created document.  But, somehow,
this is not working for me.  Maybe I am missing something.  Here is the program,

private import test.MyDDoc;   /// This is to bring PrintMe()

/// This is a comment for PrintMe2()
void PrintMe2()
{
printf("test it");
}
/// This one is a comment for main
void main()
{
int i = 0;   /// This is a comment for i
PrintMe();   /// This came from test.MyDDoc
PrintMe2();  /// <b>This is a local PrintMe2()</b>
}

The only comments appearing in the HTML file created by DDoc are,

/// This is a comment for PrintMe2()

and 

/// This one is a comment for main

the rest are not appearing.  Anyone want to explain why to me?

Thanks.

josé

PS:  Here is test.MyDDoc if someone wants to take a stab at it:

/**
+ this is a module for something
+ <br><b>line 2</b>
+ <br>line 3
*/
module test.MyDDoc;
/// This function prints hello
void PrintMe()
{
char[] Chh = "This is good";   /// This is for Chh
int i      = 3;                /// This is for i
printf("hello\n");             /// Prints hello
}

By the way, these last 3 comments also do not appear in the DDoc file.
Jun 10 2006
next sibling parent Daniel Keep <daniel.keep.lists gmail.com> writes:
If I had to guess, I'd say it's because DDoc doesn't output comments for
things inside functions, or for import lines.  It's for documenting a
module's interface, not its implementation details.

Think of it like this: if you write a library and document it with DDoc,
users of your library probably don't care that your PrintMe method has
an int called i used in the implementation: they just want to know what
the function itself does.

At least, I think that's why it isn't showing up.  I could always be
wrong :)

	-- Daniel

-- 
Unlike Knuth, I have neither proven or tried the above; it may not even
make sense.

v2sw5+8Yhw5ln4+5pr6OFPma8u6+7Lw4Tm6+7l6+7D
i28a2Xs3MSr2e4/6+7t4TNSMb6HTOp5en5g6RAHCP  http://hackerkey.com/
Jun 10 2006
prev sibling parent Carlos Santander <csantander619 gmail.com> writes:
jicman escribió:

 Greetings!
 
 According to DDoc documentation, a declaration can have a comment to the right
 of the declaration, ie.
 
 int i = 0;   /// this is for i
 
 and the comment will appear in the DDoc html created document.  But, somehow,
 this is not working for me.  Maybe I am missing something.  Here is the
program,
 
 private import test.MyDDoc;   /// This is to bring PrintMe()
 
 /// This is a comment for PrintMe2()
 void PrintMe2()
 {
 printf("test it");
 }
 /// This one is a comment for main
 void main()
 {
 int i = 0;   /// This is a comment for i
 PrintMe();   /// This came from test.MyDDoc
 PrintMe2();  /// <b>This is a local PrintMe2()</b>
 }
 
 The only comments appearing in the HTML file created by DDoc are,
 
 /// This is a comment for PrintMe2()
 
 and 
 
 /// This one is a comment for main
 
 the rest are not appearing.  Anyone want to explain why to me?
 
 Thanks.
 
 josé
 
 PS:  Here is test.MyDDoc if someone wants to take a stab at it:
 
 /**
 + this is a module for something
 + <br><b>line 2</b>
 + <br>line 3
 */
 module test.MyDDoc;
 /// This function prints hello
 void PrintMe()
 {
 char[] Chh = "This is good";   /// This is for Chh
 int i      = 3;                /// This is for i
 printf("hello\n");             /// Prints hello
 }
 
 By the way, these last 3 comments also do not appear in the DDoc file.
 
 


I don't think comments inside functions are processed by Ddoc. In fact, I don't 
remember ever seeing a doc utility that does that.

-- 
Carlos Santander Bernal
Jun 10 2006