Bug #4149: Documentation submission: syslog standard library

• Status: Closed
• Assignee: -
• Target version: -
• ruby -v: ruby 1.9.2p0

[meta (mathew murphy)]

=begin
I've been setting up a syslog server recently, so I decided I was in a good position to document syslog from the standard library. Patch against 1.9 svn head is attached.
=end

[tenderlovemaking (Aaron Patterson)]

=begin
Looks like the patch is missing?
=end

[meta (mathew murphy)]

• File syslog.patch syslog.patch added

=begin
That's very strange, I definitely remember the annoyance of having to navigate my way to it with the file selector, and my browser still has the string I typed for the description in its autocomplete history. Redmine bug perhaps?

Anyway, here it is again.
=end

[drbrain (Eric Hodel)]

=begin

On Dec 10, 2010, at 12:57, mathew murphy wrote:

Issue #4149 has been updated by mathew murphy.

File syslog.patch added

That's very strange, I definitely remember the annoyance of having to navigate my way to it with the file selector, and my browser still has the string I typed for the description in its autocomplete history. Redmine bug perhaps? 

Anyway, here it is again.

I think this is a good patch, but I would like it if you you added call-seq: declarations to note the argument types.  RDoc can't figure this out from the C calls/rb_scan_args.  :(

Also, is open only callable a single time in a process without closing?  I know on FreeBSD calling openlog(3) twice will not create separate syslog connections.  If this is a universal thing I think their should be a warning. =end

[meta (mathew murphy)]

=begin
I can't work out how to use :call-seq: and :yields: together. Can you give me an example for the open() method?

I've tried

/* :call-seq:
  *   open(ident, options, facility)
  *
  * :yields: syslog
  */

(with and without the blank line), and also tried putting the :yields: directive after the first line of the function declaration. None of those things work.

Also, your last e-mail got added to the Redmine ticket as raw HTML.

=end

[meta (mathew murphy)]

=begin
On Sat, Dec 11, 2010 at 10:25, mathew murphy [e-mail] wrote:

I can't work out how to use :call-seq: and :yields: together.
Can you give me an example for the open() method?

If anyone else knows the intricacies of how to get :yields: directives
to work in C files, please chime in.

Otherwise, can we at least get the documentation added as-is until
someone can work out how to persuade Rdoc to parse :yields: directives
in C files?

mathew

=end

[drbrain (Eric Hodel)]

=begin
On Dec 14, 2010, at 12:12, mathew wrote:

On Sat, Dec 11, 2010 at 10:25, mathew murphy [e-mail] wrote:

I can't work out how to use :call-seq: and :yields: together.
Can you give me an example for the open() method?

If anyone else knows the intricacies of how to get :yields: directives
to work in C files, please chime in.

Otherwise, can we at least get the documentation added as-is until
someone can work out how to persuade Rdoc to parse :yields: directives
in C files?

Sorry for my late response.

At this time RDoc does not support yields: in C files.

I will implement it per your example in bug #4149.

I will be importing a new RDoc into trunk this week or next.

=end

[meta (mathew murphy)]

• File syslog.c.patch syslog.c.patch added

=begin
I am (definitely) attaching an updated documentation patch with call-seq: directives, since they now work in RDoc 2.0.1.
=end

[meta (mathew murphy)]

• File syslog.c.patch syslog.c.patch added

=begin
Attaching an updated patch with information about the format string behavior of log().
=end

[drbrain (Eric Hodel)]

• File syslog.c.label_list.patch syslog.c.label_list.patch added

=begin
I think you should use label-list instead of bullet list for the constants.

There is also some trailing whitespace and Syslog::Constants is not documented preventing 100% documentation coverage for syslog.

I have generated an updated patch for you. Other than the mSyslogContstants comment it is identical. If you approve I will commit it.
=end

[drbrain (Eric Hodel)]

• Status changed from Open to Closed

=begin
I applied my version of your patch which uses label lists. Thank you for your work!
=end