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)
*/

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

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

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?

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)

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?