Project

General

Profile

Actions

Bug #4149

closed

Documentation submission: syslog standard library

Added by meta (mathew murphy) almost 14 years ago. Updated over 12 years ago.

Status:
Closed
Assignee:
-
Target version:
-
ruby -v:
ruby 1.9.2p0
Backport:
[ruby-core:33667]

Description

=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


Files

syslog.patch (6.91 KB) syslog.patch Patch against 1.9 HEAD. Comment changes only, no code changes. meta (mathew murphy), 12/11/2010 05:57 AM
syslog.c.patch (7.34 KB) syslog.c.patch Documentation patch meta (mathew murphy), 12/21/2010 02:54 AM
syslog.c.patch (7.58 KB) syslog.c.patch Updated patch against 1.9 trunk. Should be comment changes only, no code changes. meta (mathew murphy), 02/09/2011 08:45 AM
syslog.c.label_list.patch (8.21 KB) syslog.c.label_list.patch Updated patch with labeled lists, etc. drbrain (Eric Hodel), 02/09/2011 09:17 AM
Actions #1

Updated by tenderlovemaking (Aaron Patterson) almost 14 years ago

=begin
Looks like the patch is missing?
=end

Actions #2

Updated by meta (mathew murphy) almost 14 years ago

=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

Actions #3

Updated by drbrain (Eric Hodel) almost 14 years ago

=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
Actions #4

Updated by meta (mathew murphy) almost 14 years ago

=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

Actions #5

Updated by meta (mathew murphy) almost 14 years ago

=begin
On Sat, Dec 11, 2010 at 10:25, mathew murphy 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

Actions #6

Updated by drbrain (Eric Hodel) almost 14 years ago

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

On Sat, Dec 11, 2010 at 10:25, mathew murphy 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

Actions #7

Updated by meta (mathew murphy) almost 14 years ago

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

Actions #8

Updated by meta (mathew murphy) over 13 years ago

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

Actions #9

Updated by drbrain (Eric Hodel) over 13 years ago

=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

Actions #10

Updated by drbrain (Eric Hodel) over 13 years ago

  • Status changed from Open to Closed

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

Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0Like0Like0Like0Like0Like0