Project

General

Profile

Bug #4149

Documentation submission: syslog standard library

Added by meta (mathew murphy) about 9 years ago. Updated over 7 years ago.

Status:
Closed
Priority:
Normal
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

Associated revisions

Revision a6fcf3e5
Added by drbrain (Eric Hodel) almost 9 years ago

Apply documentation patch from mathew murphy. [Bug #4149]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@30938 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 30938
Added by drbrain (Eric Hodel) almost 9 years ago

Apply documentation patch from mathew murphy. [Bug #4149]

Revision 30938
Added by drbrain (Eric Hodel) almost 9 years ago

Apply documentation patch from mathew murphy. [Bug #4149]

Revision 30938
Added by drbrain (Eric Hodel) almost 9 years ago

Apply documentation patch from mathew murphy. [Bug #4149]

Revision 30938
Added by drbrain (Eric Hodel) almost 9 years ago

Apply documentation patch from mathew murphy. [Bug #4149]

Revision 30938
Added by drbrain (Eric Hodel) almost 9 years ago

Apply documentation patch from mathew murphy. [Bug #4149]

Revision 30938
Added by drbrain (Eric Hodel) almost 9 years ago

Apply documentation patch from mathew murphy. [Bug #4149]

History

#1

Updated by tenderlovemaking (Aaron Patterson) about 9 years ago

=begin
Looks like the patch is missing?
=end

#2

Updated by meta (mathew murphy) about 9 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

#3

Updated by drbrain (Eric Hodel) about 9 years ago

=begin
On Dec 10, 2010, at 12:57, mathew murphy wrote:Issue #4149 has been updated by mathew murphy.File syslog.patch addedThat'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

#4

Updated by meta (mathew murphy) about 9 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

#5

Updated by meta (mathew murphy) almost 9 years ago

=begin
On Sat, Dec 11, 2010 at 10:25, mathew murphy redmine@ruby-lang.org 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

#6

Updated by drbrain (Eric Hodel) almost 9 years ago

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

On Sat, Dec 11, 2010 at 10:25, mathew murphy redmine@ruby-lang.org 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

#7

Updated by meta (mathew murphy) almost 9 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

#8

Updated by meta (mathew murphy) almost 9 years ago

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

#9

Updated by drbrain (Eric Hodel) almost 9 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

#10

Updated by drbrain (Eric Hodel) almost 9 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

Also available in: Atom PDF