• Max Samukha (9/9) Mar 01 2008 In the following example, the custom section header and contents are
• Max Samukha (3/12) Mar 03 2008 Yeah, my clock has gone unruly
• Derek Parnell (15/26) Mar 03 2008 Try this ...
• Max Samukha (4/21) Mar 04 2008 Thanks. I should have deduced that from See_Also section name. Are the
• Robert Fraser (29/57) Mar 04 2008 Basically, you can name sections any st of alphanumeric
• Max Samukha (12/40) Mar 04 2008 Yeah, I had read that. Still, the spec says nothing about what a valid

Max Samukha <samukha voliacable.com.removethis> writes:

In the following example, the custom section header and contents are
rendered as part of foo's descrition. I have not been able to persuade
DDoc to make it a new section. Anybody knows how to do that?

/**
    Params:
	foo     = bar

$(DDOC_SECTION_H Section header:)
$(DDOC_SECTION Section contents)
*/

Max Samukha <samukha voliacable.com.removethis> writes:

On Sun, 02 Mar 2008 08:51:55 +0200, Max Samukha
<samukha voliacable.com.removethis> wrote:

In the following example, the custom section header and contents are
rendered as part of foo's descrition. I have not been able to persuade
DDoc to make it a new section. Anybody knows how to do that?

/**
    Params:
	foo     = bar

$(DDOC_SECTION_H Section header:)
$(DDOC_SECTION Section contents)
*/

Yeah, my clock has gone unruly

Derek Parnell <derek nomail.afraid.org> writes:

On Sun, 02 Mar 2008 08:51:55 +0200, Max Samukha wrote:

 In the following example, the custom section header and contents are
 rendered as part of foo's descrition. I have not been able to persuade
 DDoc to make it a new section. Anybody knows how to do that?
 
 /**
     Params:
 	foo     = bar
 
 $(DDOC_SECTION_H Section header:)
 $(DDOC_SECTION Section contents)
 */

Try this ...

/**
    Params:
	foo     = bar

    Section_Header:
    Section contents

*/

A Section name can only consist of ASCII alphabetic characters and '_'. The
'_' is converted to a space on rendering.

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
4/03/2008 6:21:04 PM

Max Samukha <samukha voliacable.com.removethis> writes:

On Tue, 4 Mar 2008 18:29:45 +1100, Derek Parnell
<derek nomail.afraid.org> wrote:

On Sun, 02 Mar 2008 08:51:55 +0200, Max Samukha wrote:

 /**
     Params:
 	foo     = bar
 
 $(DDOC_SECTION_H Section header:)
 $(DDOC_SECTION Section contents)
 */

Try this ...

/**
    Params:
	foo     = bar

    Section_Header:
    Section contents

*/

A Section name can only consist of ASCII alphabetic characters and '_'. The
'_' is converted to a space on rendering.

Thanks. I should have deduced that from See_Also section name. Are the
section naming rules mentioned anywhere in the spec?

Robert Fraser <fraserofthenight gmail.com> writes:

Max Samukha wrote:
 On Tue, 4 Mar 2008 18:29:45 +1100, Derek Parnell
 <derek nomail.afraid.org> wrote:
 
 On Sun, 02 Mar 2008 08:51:55 +0200, Max Samukha wrote:

 /**
     Params:
 	foo     = bar

 $(DDOC_SECTION_H Section header:)
 $(DDOC_SECTION Section contents)
 */

 Try this ...

 /**
    Params:
 	foo     = bar

    Section_Header:
    Section contents

 */

 A Section name can only consist of ASCII alphabetic characters and '_'. The
 '_' is converted to a space on rendering.

 
 Thanks. I should have deduced that from See_Also section name. Are the
 section naming rules mentioned anywhere in the spec?

Basically, you can name sections any st of alphanumeric 
characters/underscores you want and the underscores are converted to 
spaces in the output. The text is treated as a section if a line begins 
with a valid section identifier followed by a colon.

http://www.digitalmars.com/d/2.0/ddoc.html

Look under "Sections" about halfway down. The sections the DMD Ddoc 
generator recognizes specially are:
- Summary
- Description
- Copyright
- Params
- Macros

There are some others specified by the docs, but these aren't treated 
any differently than regular sections you make up:
- Authors
- Bugs
- Date
- Deprecated
- Examples
- History
- License
- Returns
- See_Also
- Standards
- Throws
- Version

(FYI, if you're using Descent, the "Returns" section for a function is 
given a special meaning in doc views)

Max Samukha <samukha voliacable.com.removethis> writes:

On Tue, 04 Mar 2008 02:33:24 -0800, Robert Fraser
<fraserofthenight gmail.com> wrote:

Basically, you can name sections any st of alphanumeric 
characters/underscores you want and the underscores are converted to 
spaces in the output. The text is treated as a section if a line begins 
with a valid section identifier followed by a colon.

http://www.digitalmars.com/d/2.0/ddoc.html

Yeah, I had read that. Still, the spec says nothing about what a valid
section identifier is.
 
Look under "Sections" about halfway down. The sections the DMD Ddoc 
generator recognizes specially are:
- Summary
- Description
- Copyright
- Params
- Macros

There are some others specified by the docs, but these aren't treated 
any differently than regular sections you make up:
- Authors
- Bugs
- Date
- Deprecated
- Examples
- History
- License
- Returns
- See_Also
- Standards
- Throws
- Version

(FYI, if you're using Descent, the "Returns" section for a function is 
given a special meaning in doc views)

Descent is cool, but unfortunately Eclipse does not run acceptably on
the retarded hardware I have to use.

I wish $(DDOC_SECTION_H) in doc comments was treated specially and
started a new section allowing for non-alphanumeric characters in
section headers.

For example, I need a section with () in its header, right after the
Params: section. Is there any way to do that?